From 1da054bebec2ceaf18037e4ec0b72753456e9d1b Mon Sep 17 00:00:00 2001 From: BigSimmo <87357024+BigSimmo@users.noreply.github.com> Date: Wed, 19 Aug 2026 03:32:40 +0800 Subject: [PATCH 001/156] docs(caring-contacts): binding spec for the synthetic production build Records the nine decision-lock revisions agreed 19 August 2026 (auto-reply to inbound messages, closing message at month 12, coordinator-set first contact date, third-party pause, cultural-identity reach reporting, configurable retention with real deletion, message rules as data, the enforced repository seam, and one bounded clinical-record document). Specifies the domain rules layer, a dedicated caring-contact Supabase project kept hard-separated from the Clinical KB project, the seven screens required by existing decisions but never designed, four recommended screens, the design non-regression contract, the elevation brief, and the open governance register. Synthetic data only. No SMS provider, no real patient data, no migration against the Clinical KB project, no production deployment. Co-Authored-By: Claude Opus 5 --- ...-caring-contact-production-build-design.md | 450 ++++++++++++++++++ 1 file changed, 450 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-19-caring-contact-production-build-design.md diff --git a/docs/superpowers/specs/2026-08-19-caring-contact-production-build-design.md b/docs/superpowers/specs/2026-08-19-caring-contact-production-build-design.md new file mode 100644 index 000000000..5ce32c340 --- /dev/null +++ b/docs/superpowers/specs/2026-08-19-caring-contact-production-build-design.md @@ -0,0 +1,450 @@ +# Caring Contact production build — binding design specification + +**Status:** synthetic production build, approved 19 August 2026. No real patient data, no SMS provider, no +migration against the Clinical KB project, and no production deployment. Hosted migrations against the +dedicated caring-contact Supabase project are permitted with confirmation at the time (§3.2). + +**Relationship to earlier documents.** This extends the +[rollout plan](../plans/2026-08-14-caring-contact-coordination-rollout.md) and the +[coordination design spec](2026-08-15-caring-contact-coordination-design.md). Where this document and +the 15 August decision lock disagree, §2 records the revision and this document wins. + +**Design system:** [SPEC](../../design-system/SPEC.md), [TOKENS](../../design-system/TOKENS.md), +[COMPONENTS](../../design-system/COMPONENTS.md), [GATES](../../design-system/GATES.md). + +## 1. Purpose and standing + +The design phase is complete. The linked prototype, screenshot atlas, interaction matrix, accessibility +acceptance and clinical-language trace landed in PR #2095; the decision lock, design-phase plan and +coordination spec landed in PR #2133. + +This specification covers the next tranche: **a genuinely working caring-contact coordination workspace +running on synthetic patients**, comprising the domain rules layer, a real datastore, and the complete +production screen set. + +**Programme context that sets the sequencing.** The destination remains a real WA Health pilot. No +sponsoring service, executive sponsor or governance route exists yet. Real patient data is therefore not +available for at least six months, and the hosting, privacy-impact, enterprise sign-on, records and +SMS-procurement work cannot be specified against requirements nobody has written. The artefact that +unlocks all of it is a complete, credible, working system on synthetic data, built to a standard that +will not need rebuilding. That is what this document specifies. + +## 2. Decision-lock revisions — 19 August 2026 + +The Approved decision lock of 15 August 2026 remains binding except for the following nine revisions. +Each records its reasoning so a later reviewer re-opens it deliberately rather than by accident. + +### 2.1 Replies receive an automated non-monitored response + +**Was:** "Use a non-receiving sender. Callback receives, stores, analyses and displays no replies." + +**Now:** patient-visible messages originate from a **receiving-capable dedicated number**. Any inbound +message triggers an immediate automated response naming the programme line and its hours, one approved +crisis-support contact, and emergency direction. Inbound content is **discarded at the provider boundary +and never persisted, transmitted to Callback, displayed, logged, counted per patient, or analysed**. +Callback still has no inbox, no thread, no reply workflow, and no per-patient reply signal. + +**Reasoning:** a non-receiving sender leaves a distressed patient who replies with either a carrier error +or complete silence, immediately after a message from a mental-health team. Silence is the worst +clinically available outcome, and it was previously being decided by a carrier default rather than by the +service. The automated response removes the silence while preserving the one-way boundary in substance: +nothing is received, stored, seen, or acted upon by a human. + +**Consequences:** the provider adapter must support inbound auto-response with non-persistence; provider +selection criteria change; privacy review must confirm the position because inbound content transits the +provider even though it is never retained. + +### 2.2 The pathway ends with a closing message + +**Was:** the cadence ends silently after the month-12 contact. + +**Now:** the month-12 contact is a distinct governed message type, `closing`, stating plainly that this +is the final message, thanking the person, and repeating the programme line while it remains open, their +usual services, and crisis support. It requires its own clinical-programme-lead and lived-experience +approval, separately from the ordinary variants. + +**Reasoning:** ending a year of contact from a mental-health team without naming the ending risks being +experienced as being forgotten. The closing message costs nothing operationally. + +### 2.3 The coordinator sets the first contact date + +**Was:** "The first message uses the next occurrence of the patient's approved sending time." + +**Now:** the coordinator selects the first contact date during activation. It **defaults to the day after +discharge**, may be moved within **the discharge day to seven days after discharge inclusive**, and any +value other than the default requires a recorded reason. All later contacts derive from the original +discharge anchor; moving the first contact never rebases the twelve-month calendar. + +**Reasoning:** the previous rule could place the first caring contact roughly an hour after discharge, +plausibly while the person is still leaving the hospital, and made behaviour depend on the exact minute a +discharge was recorded. + +**Consequences:** the review-and-activation screen gains a first-contact-date control. The existing +mockup does not show it and is now known to be out of date on that screen. + +### 2.4 Authorised staff may pause on a third-party request + +**Was:** only the patient, via the programme line, or the source system may change a plan. + +**Now:** any authorised team member may **pause** future contacts immediately on a third-party request — +family, carer, or another clinician — recording who made the request, their stated relationship, and what +was said. **Permanent withdrawal and recording a death still require the patient or the source system.** +A third-party pause creates a coordinator-review exception. + +**Reasoning:** a relative reporting a death not yet in the source system, or a carer reporting distress +caused by the messages, previously had no path other than waiting for records to catch up. Pausing is +always the safe direction to be wrong in. Permanent withdrawal stays restricted so that a third party +cannot end a service the patient chose. + +### 2.5 Cultural identity is imported for reach reporting only + +**Was:** unaddressed. + +**Now:** Aboriginal and Torres Strait Islander status is imported from the source record and used for +exactly one purpose: **aggregate reporting on programme reach**, with a governance-configured small-cell +threshold and a non-inferable `Suppressed` state. It **never** affects eligibility, ordering, timing, +pathway assignment, message content, or any ranking, and never appears on a worklist row. + +**Reasoning:** Aboriginal and Torres Strait Islander people in WA experience substantially higher suicide +rates. A programme that cannot report whether it reaches them cannot answer the first equity question a +WA mental-health governance board asks. Restricting the field to aggregate reporting keeps the benefit +without introducing demographic-driven clinical behaviour. + +**Consequences:** a culturally appropriate pathway is explicitly out of scope here — that content must be +authored and approved by Aboriginal health and lived-experience representatives. An Aboriginal health +review joins the pre-pilot register (§14). + +### 2.6 Retention is configurable with real deletion + +**Was:** "the formally approved retention period", unspecified. + +**Now:** retention is a **configured policy value, not a code constant**, with a **working assumption of +seven years** from episode completion. The data model supports genuine erasure of patient-identifying +fields while the **audit trail survives in de-identified form**, retaining actor, action, timestamp, +object type and outcome. + +**Reasoning:** a records officer sets the real figure and this build must not pre-empt them. Retrofitting +erasure onto a schema that assumed permanence is expensive and error-prone. + +### 2.7 Message rules are data, not code + +**Now:** `validateGovernedMessage` is mechanism only. The rules live in a single separate module marked +**provisional and not clinically approved**, seeded from the decision lock's prohibited concepts, the +existing `EXACT_PATIENT_VISIBLE_MESSAGE` and `PATIENT_VISIBLE_NO_REPLY_NOTICE` constants, and the +two-segment GSM-7 limit. Replacing that module must not require touching the validator. + +**Reasoning:** the promised `content-style-guide.md` was never written. Embedding rules in the validator +would turn an agent's guess into clinical policy. + +### 2.8 The workspace stays in this repository behind an enforced seam + +**Now:** all domain rules live under `src/lib/caring-contacts/` and **import nothing from outside that +directory** except the TypeScript and Node standard libraries, enforced by a test that fails on any +outward import. Caring-contact database migrations live under `caring-contacts/supabase/migrations/` and **must +never be placed in `supabase/migrations/`**, which is replayed against the live Clinical KB project. UI +may depend on the repository design system as normal. + +**Reasoning:** the repository supplies the design system, accessibility primitives, gates and test +harness immediately. A real-patient deployment cannot share a codebase, database or deployment with the +Clinical KB search tool, so the extraction path must be a directory move rather than an untangling +performed under time pressure. + +### 2.9 One narrowly bounded patient-level document is permitted + +**Was:** "The pilot permits no patient-level export." + +**Now:** exactly one patient-level artefact is permitted: a **plan summary for filing in the patient's +hospital record**, containing the plan, pathway version, dates, owning team and coordinator. It contains +**no mobile number, no message text and no clinical detail**. Every generation is audited with actor, +timestamp and purpose. No other export, download, or bulk extract exists. + +**Reasoning:** the structured record write-back is the primary channel, but hospital services routinely +require a filed document, and an unscoped later exception is more dangerous than a bounded one written +now. The prohibition otherwise stands. + +## 3. Architecture + +### 3.1 The sealed domain layer + +``` +src/lib/caring-contacts/ + model.ts plan/contact/template/referral lifecycles and legal transitions + schedule.ts discharge-anchored calendar construction + hospital-events.ts readmission, death, correction, contact-change transitions + permissions.ts deny-by-default, team-scoped capability checks + message-policy.ts governed-message validation mechanism + message-rules.ts PROVISIONAL rule data; replaced wholesale on clinical approval + audit.ts immutable audit event construction + retention.ts retention policy evaluation and de-identification + clock.ts injected time source; no ambient time in domain code + repository.ts storage interface + db/ Postgres implementation of the storage interface +``` + +No file under `src/lib/caring-contacts/` may import from `@/components`, `@/app`, any `@/lib` module +outside itself, Supabase, or OpenAI. `tests/caring-contacts-domain-isolation.test.ts` enforces this by +parsing every import specifier in the directory. + +### 3.2 Datastore + +A **dedicated Supabase project, separate from the Clinical KB project**, holding synthetic data only. + +**Hard separation rules.** + +- The Clinical KB project `sjrfecxgysukkwxsowpy` is **never** the target. Caring-contact tables must not + be created in it under any circumstances. +- Caring-contact migrations live under `caring-contacts/supabase/migrations/` and **never** in the + repository's `supabase/migrations/`, which is replayed against the Clinical KB project. +- Connection configuration uses its own environment variables, distinct from every existing + `NEXT_PUBLIC_SUPABASE_*` and `SUPABASE_*` value. No credential is shared between the two projects. +- `npm run check:supabase-project`, which pins the Clinical KB reference, must continue to pass unchanged. + A new check asserts the caring-contact configuration never resolves to the pinned reference. +- Region **ap-southeast-2 (Sydney)**, matching the residency requirement even though this project holds no + real patient data, so the eventual production posture is rehearsed rather than retrofitted. + +**Schema requirements.** Team-scoped row-level security enforced in the database rather than only in +application code; audit rows written in the same transaction as the change they describe; unique +constraints preventing a second active plan per patient and duplicate contact dispatch; idempotency keys +on every write; and the §2.6 de-identification path proven by migration test. + +**Provisioning is a gated action.** Creating the project, choosing its plan and applying the first hosted +migration each require explicit confirmation at the time, recorded in §14. Until it exists, the same +schema runs against a local Postgres instance so development is never blocked. + +### 3.3 Key interfaces + +- `buildApprovedSchedule(input): ScheduleResult` — pure and deterministic. Anchored to actual discharge + time; cadence day 1, week 1, months 1, 2, 3, 4, 6, 8, 10, 12; window preference maps to 10:00, 14:00 or + 17:00 AWST; month arithmetic clamps to the last day of a shorter month; weekends and WA public holidays + send normally; the coordinator's first-contact date (§2.3) shifts only the first contact; the month-12 + contact is typed `closing`. +- `applyHospitalStatusEvent(plan, event): PlanTransition` — readmission pauses future contacts; a recorded + death irreversibly cancels every unsent contact; a death correction produces an incident transition and + never resumes the episode; a source mobile change pauses and raises an exception. +- `canPerformCaringContactAction(actor, action, resource): CapabilityDecision` — deny by default, + team-scoped, returning a named reason for every denial so the interface can explain itself (§5.4). +- `validateGovernedMessage(input): ValidationResult` — exact blocking codes, never calls a model or + provider, rules sourced from `message-rules.ts`. + +### 3.4 Time and identity in the synthetic build + +All domain functions take an injected clock; no domain module reads ambient time. Sign-in is a +**non-production role switcher** (coordinator, team lead, auditor) rather than real credentials: the +decision lock requires WA Health enterprise sign-on and states that no Callback-local credentials exist, +so building a login would violate it, and the permission and auditor surfaces cannot be demonstrated +without role switching. + +## 4. Screen inventory + +### 4.1 Existing screens — elevated, not redesigned + +Today, Patients, patient detail, the four-stage activation, plan detail, Schedule, contact detail, +Templates, pathway detail, Team, Guidance, Reports and all 24 overlays in +[the interaction matrix](../../caring-contacts/interaction-matrix.md) carry forward. §6 governs what may +change; §7 lists the permitted improvements. + +### 4.2 New screens required by existing decisions + +Each is demanded by a rule already in the decision lock and currently has no surface. + +| Screen | Rule it satisfies | Notes | +| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Service safety stop** | A confirmed wrong-recipient message, duplicate send, unauthorised content, material privacy/security incident or loss of audit integrity immediately pauses the entire pilot | Service-wide halt of all sending across every patient and team, with a categorised reason and acting person. Restart requires recorded joint approval from the incident lead, privacy/security owner and clinical programme lead; the interface must not permit single-person restart. A service-state banner is visible everywhere while active. | +| **Pathway authoring and dual approval** | A clinical programme lead and a lived-experience representative both approve new or materially changed pathway/message versions | Draft, review, dual approval with named approvers and timestamps, publication, retirement, immutable version snapshots. Active plans keep their snapshot; an urgent safety retirement pauses affected future contacts for explicit review. | +| **Provider reconciliation** | Staff perform manual provider reconciliation when an outage, discrepancy or suspected incident occurs | Callback's expected dispatch record beside reported provider status for a bounded window; explicit resolution of each discrepancy; never automatically resends an uncertain contact. | +| **Auditor access trail** | Clinicians see episode-relevant history; privacy/security auditors see the complete access trail | Role-gated, read-only, filterable view of every search, view, decision, mutation, write-back and administrative access. | +| **Workload and queue monitor** | The pilot has no numeric cap, so workload monitoring and stopping rules are mandatory | Queue age, unclaimed work against the 60-minute escalation, active plans per coordinator, exception backlog age. Operational only; never ranks clinicians. | +| **Notification preferences** | Alerts contain no patient identifiers and require authentication | Per-user opt-in by alert class, with a preview demonstrating the identifier-free alert body. | +| **Training and assessed simulation** | Production access requires assessed simulation of identity review, activation, withdrawal, delivery failure, readmission, downtime and incident handling | A badged sandbox with its own synthetic cohort, scenario scripts for each competency, and a per-user completion record. Never shares data with the live workspace; a persistent training indicator on every screen. | + +### 4.3 New screens recommended and approved + +| Screen | Why | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Episode timeline** | One chronological record per episode — referral received, accepted, claimed, activated, each contact, pauses, exceptions, reassignment, closing message. The first thing anyone asks for after an incident. | +| **Coverage and absence** | Who covers which coordinator and for how long, with the named coordinator and any formal reassignment still visible. | +| **Equity reach report** | The §2.5 aggregate section within Reports, with small-cell suppression. | +| **Clinical-record plan summary** | The §2.9 bounded document, generated and audited. | + +### 4.4 Cross-cutting interaction: explained automation + +Wherever the system has acted on its own — paused, skipped, suppressed, blocked, escalated — the surface +stating that state must also state, in plain words and in place, **why** and **what would change it**. No +bare status chip without a reachable reason. This is a contract asserted in DOM tests for every automated +state, not a visual preference. + +## 5. Phone + +- **Installable, network-required.** The workspace may be installed to a home screen. It must not cache + patient data, must not function offline, and must fail closed with the approved downtime message when + connectivity is lost, following directly from "no offline patient cache" and "downtime fails closed". +- **Deliberately narrower than desktop.** The compact build prioritises today's queue, work needing + action, the episode currently being handled, and an immediate pause. Pathway authoring, reconciliation, + the auditor trail and reporting are desktop-first; at compact widths they present a readable summary and + an explicit statement that the task is better performed on a larger screen, rather than a cramped + reproduction. +- The four-item dock, More sheet, safe areas, edge-to-edge behaviour and the repository phone-chrome + contract in `docs/search-chrome-behaviour.md` continue to govern. +- Chromium at 320/390/430 is layout evidence only. Physical iPhone Safari and installed-PWA acceptance + remain open (§14). + +## 6. Design non-regression contract + +The approved visual design is a baseline, not a starting point. Improvement is in scope; drift is not. + +**Frozen — may not change without a recorded decision:** + +1. The screen and overlay inventory of the coordination design spec §6, as extended by §4. +2. The 24-row modality and dismissal decisions in `interaction-matrix.md`. +3. The width-to-state mapping (`compact` / `rail` / `split` / `wide`). +4. The closed transport vocabulary and every prohibited clinical term. +5. Token usage: no hardcoded colour, no new colour semantics, no decorative clinical colour. +6. The continuity thread's meaning — elapsed schedule spacing only, never patient, delivery or clinical + state. + +**Enforcement.** Existing DOM and Playwright suites carry forward unweakened; no existing assertion may be +deleted or loosened to accommodate a change. The 44-image screenshot atlas is re-captured after each screen +wave and compared against the committed baseline. Every intentional visual difference is listed and +justified at a checkpoint; any unexplained difference is a regression. + +## 7. Elevation brief + +Named, testable improvements. Anything not listed is out of scope for "improvement" and needs a decision +first. + +1. **Today earns its first screen.** Referrals-to-review and needs-action legible at a glance at every + width, each row naming the observable condition, the remedy and the owner. Reporting stays below + actionable work. +2. **Every empty state does work.** No bare "nothing here": state what will appear, why it is empty now, + and the single available action if one exists. +3. **Every automated state explains itself** (§4.4). +4. **Denials say why.** `canPerformCaringContactAction` returns a reason and the interface shows it, using + the repository's `aria-disabled` plus stated-reason pattern rather than a hidden or inert control. +5. **Identity stays anchored.** The patient under work remains visible through every activation stage and + every overlay; `Change patient` keeps object-specific confirmation. +6. **Dates are unambiguous.** `en-AU` display with weekday and explicit AWST window; machine ISO retained + underneath; never a bare dash for a missing value. +7. **Keyboard operation is first-class.** Visible focus at every step, correct focus return from all 24 + overlays, no keyboard trap, sensible order through the four-stage flow. +8. **Forced colours, dark mode, reduced motion and 400% reflow** proven per screen rather than sampled. + +## 8. Rules layer — behaviour to prove + +Written test-first; each is an assertion, not a description. + +- Discharge anchoring, all ten cadence points, month-end clamping, leap dates, and the §2.3 first-contact + window including both boundaries and the reason requirement. +- Windows map to exactly 10:00/14:00/17:00 AWST; one preference per plan; no episode rotates windows. +- Weekends and WA public holidays send; nothing sends outside 09:00–18:00. +- Missed contacts are recorded, never sent late; the calendar never rebases. +- Pause preserves the original calendar and permanently skips contacts inside the pause; resumption begins + at the next future contact. +- Withdrawal cancels all unsent contacts immediately, needs no approval, retains immutable history. +- Readmission pauses; recorded death irreversibly cancels; death correction raises an incident and never + resumes. +- A duplicate referral for an active plan is blocked and routed to the existing episode; a later qualifying + discharge creates a new linked episode and never mutates the earlier one. +- Transient transport failure retries twice, three attempts total, strictly inside the original window. +- Permanent failure pauses future contacts and raises a same-day task, never contacting the patient + automatically. +- Third-party pause (§2.4) records requester and relationship; third-party withdrawal is refused with a + named reason. +- Every substituted message including notices and signature fits two GSM-7 segments; overflow blocks with an + exact count. +- Permissions deny by default, are team-scoped, and refuse cross-team access with a reason. +- Every mutation writes its audit event in the same transaction; no code path can write one without the + other. +- Retention de-identification removes patient fields and preserves actor, action, timestamp, object type and + outcome. +- A full twelve-month simulation produces exactly ten contacts in the correct order with zero duplicates + under retries, concurrent pause and clock jitter. + +## 9. Data model additions + +Beyond the rollout plan's Phase 6 model: the coordinator-selected first contact date and its reason; the +`closing` message type; third-party pause requester and relationship; imported Aboriginal and Torres Strait +Islander status held in a reporting-only projection separate from operational patient fields; retention +policy value and de-identification state; training-mode ownership so simulation data can never join live +queries; service state (safety stop) as a first-class object with reason, actor and three restart +approvals; and clinical-record summary generation events. + +## 10. Non-production affordances + +### 10.1 Demo clock + +A non-production-only control advancing the injected clock so a reviewer can see month 1, 6 or 12 without +waiting. Never present in a production build; guarded by the same environment-gate pattern as +`mockupsEnabled`, and asserted absent by a production-build test. + +### 10.2 Synthetic caseload + +At least twelve obviously fictional patients spread across referral, awaiting claim, active early, active +late, paused, withdrawn, readmitted, permanent delivery failure and completed states, so no screen is ever +demonstrated empty. + +### 10.3 Training mode + +Per §4.2, with its own cohort, persistent indicator, scenario scripts for the seven required competencies +and a per-user completion record. Built last so it can slip without blocking anything else. + +## 11. Verification + +- Focused Vitest per rules module, written before implementation. +- Domain isolation test (§3.1) and a test asserting no caring-contact migration reaches the repository `supabase/migrations/` directory, and that caring-contact configuration never resolves to the pinned Clinical KB project reference. +- Migration tests for team scoping, transactional audit, duplicate prevention and de-identification. +- DOM tests per screen, including the explained-automation and empty-state contracts. +- Repository-wrapped Playwright journeys at 320/390/430/768/1024/1440, plus dark, forced colours, reduced + motion and 400% reflow. +- Screenshot atlas re-capture and justified-difference review at each checkpoint (§6). +- `npm run verify:pr-local` once per pull request; `npm run verify:ui` once for the screen pull request. +- No provider-backed gate. `check:production-readiness` remains intentionally gated without live + configuration. + +## 12. Out of scope + +No SMS provider, no real patient data, no migration of any kind against the Clinical KB Supabase project, +no production deployment, no hosting change for real-patient use, no enterprise sign-on, and no +clinical-record write-back adapter beyond the synthetic interface. + +Hosted migrations against the **dedicated caring-contact Supabase project** are in scope, but each apply +requires explicit confirmation at the time (§3.2). + +Refused on safety grounds regardless of convenience: bulk actions across patients; offline access or any +device-local patient storage; storing, displaying, counting per patient, or acting on replies; any risk +score, prediction, ranking or clinician league table; and search beyond the acting team's own referrals and +episodes. + +## 13. Delivery + +**Two pull requests, two checkpoints.** + +1. **Rules and datastore** — §3, §8, §9, plus documentation repairs: the broken `design-handoff.md` + reference, the seeded provisional message rules, and the rollout plan's progress record. Checkpoint one. +2. **Screens** — §4, §6, §7, then §10. Checkpoint two. + +Each piece is one agent, written test-first, adversarially reviewed by a second agent before it counts as +done, and committed separately so any single piece can be reverted while the pull request is open. + +## 14. Open register — recorded, not solved + +None blocks this build; all block a real-patient pilot. + +| Item | Owner | Note | +| ------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Aboriginal health and cultural safety review | Aboriginal health governance | Required before any real patient; a culturally appropriate pathway is separate approved work. | +| Hosting: Railway has no Australian region | Josh, then a sponsoring service | The app tier runs in Singapore; the decision lock requires Australian residency for data, backups, logs and provider processing. A real-patient deployment needs a separately contracted Australian PHI-capable environment. | +| Provisioning the dedicated caring-contact Supabase project | Josh | Creating the project, its plan and cost, and the first hosted migration each need confirmation at the time. Sydney region. Synthetic data only. Development proceeds against local Postgres until it exists. | +| A shareable hosted demo instance | Josh | The dedicated Supabase project makes the data shareable; serving the application to someone else is a further decision, since the app tier would still run outside Australia. Acceptable for synthetic data, not for real patients. | +| Staff supervision and vicarious distress | Clinical programme lead | Coordinators carry a caseload of recent suicidal crises; no supervision model exists. | +| Wrong-recipient contact runbook | Service | What happens when an unconnected person receives a message and rings the programme line. | +| Death during the programme: notification and team support | Clinical programme lead | Cancellation is mechanical; who is told, and what support the coordinator receives, is unspecified. | +| Equity limitation: people without a patient-controlled mobile | Josh, for the governance submission | Eligibility systematically excludes some of the most marginalised patients. State it rather than be asked. | +| Provider inbound auto-response privacy position (§2.1) | Privacy review | Inbound content transits the provider even though it is never retained. | +| Retention figure | Records officer | Seven years is a working assumption only. | +| Sponsor case, costing and demonstration | Josh | No artefact yet addresses a clinical director rather than an engineer. | +| Physical iPhone Safari and installed-PWA acceptance | Josh | Chromium evidence cannot close it. | + +## 15. Approval boundary + +This specification is not clinical approval, WA Health endorsement, evidence of clinical effectiveness, or +production readiness. It authorises a synthetic build only. From 363417175714717237b5103424c0cfd92566c030 Mon Sep 17 00:00:00 2001 From: BigSimmo <87357024+BigSimmo@users.noreply.github.com> Date: Wed, 19 Aug 2026 03:52:40 +0800 Subject: [PATCH 002/156] docs(caring-contacts): rename to Caring Contacts and add the missing governance artefacts Renames the service from Callback (41 occurrences across the rollout plan, the coordination spec, the production build spec and the prototype shell header). Callback named a promise the service never keeps: it never calls back, never receives a reply and never responds. A patient enrolled in "Callback" could reasonably expect a telephone call, which is the same expectation-mismatch hazard as the silent-reply problem corrected on 19 August. Recorded as decision revision 2.10. No test asserted the old name; the 38 focused caring-contact tests pass unchanged. Adds five artefacts the programme lacked: - hazard-log.md: 30 clinical, patient-facing, scheduling, privacy and operational hazards with severity, controls, status and named owner. Six are unmitigated and block a pilot. - evidence-brief.md: the honest evidence position for a sponsor, including the equivocal meta-analyses and null replications. Citations are explicitly marked unverified and must be checked before use. - referral-feasibility.md: the questions to ask about the WA hospital referral feed, who to ask, and the manual-entry fallback. Largest programme risk. - message-review-pack.md: how to run the lived-experience review, and the reply-boundary wording correction it must settle first. - demo-script.md: the five-minute path through the built system. Repairs the binding reference to design-handoff.md, a file that never existed, repointing both mentions at interaction-matrix.md, which holds the 24-row modality matrix. The documentation link gate passed over this for days; queued as its own ledger request. Queues six outstanding-work requests covering the blocking hazards, the now inaccurate reply wording, referral feasibility, build status, the Australian hosting gap and the link-gate defect. Co-Authored-By: Claude Opus 5 --- docs/caring-contacts/demo-script.md | 95 ++++++++++++++++ docs/caring-contacts/evidence-brief.md | 81 ++++++++++++++ docs/caring-contacts/hazard-log.md | 82 ++++++++++++++ docs/caring-contacts/message-review-pack.md | 101 ++++++++++++++++++ docs/caring-contacts/referral-feasibility.md | 87 +++++++++++++++ .../0f9238c1-8add-450c-92d1-917376761248.json | 14 +++ .../6a617628-6b65-4f7f-b361-f96da2d0880a.json | 14 +++ .../73810780-d91c-403f-96ab-e659a75c8688.json | 14 +++ .../82838fb1-7ed2-4f37-bd50-191a603ecd0f.json | 14 +++ .../ba2bdfba-b1e1-4e13-83b4-8cb0f3ddc092.json | 14 +++ .../ebf42f52-3e74-484f-81cd-ebcbd4954b10.json | 14 +++ ...-14-caring-contact-coordination-rollout.md | 62 +++++------ ...8-15-caring-contact-coordination-design.md | 11 +- ...-caring-contact-production-build-design.md | 78 ++++++++++---- .../mockups/caring-contact-shell-frame.tsx | 6 +- 15 files changed, 627 insertions(+), 60 deletions(-) create mode 100644 docs/caring-contacts/demo-script.md create mode 100644 docs/caring-contacts/evidence-brief.md create mode 100644 docs/caring-contacts/hazard-log.md create mode 100644 docs/caring-contacts/message-review-pack.md create mode 100644 docs/caring-contacts/referral-feasibility.md create mode 100644 docs/outstanding-issues-inbox/0f9238c1-8add-450c-92d1-917376761248.json create mode 100644 docs/outstanding-issues-inbox/6a617628-6b65-4f7f-b361-f96da2d0880a.json create mode 100644 docs/outstanding-issues-inbox/73810780-d91c-403f-96ab-e659a75c8688.json create mode 100644 docs/outstanding-issues-inbox/82838fb1-7ed2-4f37-bd50-191a603ecd0f.json create mode 100644 docs/outstanding-issues-inbox/ba2bdfba-b1e1-4e13-83b4-8cb0f3ddc092.json create mode 100644 docs/outstanding-issues-inbox/ebf42f52-3e74-484f-81cd-ebcbd4954b10.json diff --git a/docs/caring-contacts/demo-script.md b/docs/caring-contacts/demo-script.md new file mode 100644 index 000000000..4449769ef --- /dev/null +++ b/docs/caring-contacts/demo-script.md @@ -0,0 +1,95 @@ +# Caring Contacts — five-minute demonstration script + +**Status:** draft, 19 August 2026. Owner: Josh. To be rehearsed once the synthetic build exists. + +**Why this document exists.** There will be roughly twenty-five screens and about five minutes in front of +a clinical director. The path through the system should be decided deliberately, built for, and rehearsed +— not discovered live. It also tells the build what "done enough to show someone" means, which is +otherwise a matter of opinion. + +**Audience.** A clinical director, mental health service manager, or governance chair. Assume they are +interested, sceptical about digital projects, and short of time. + +**Preconditions.** The synthetic caseload is loaded, the demo clock is available, and the message set has +been through the lived-experience review — never demonstrate wording that has not been reacted to by +someone with lived experience. + +--- + +## The frame, before touching anything (30 seconds) + +Say three things, and no more: + +1. What it is: one-way supportive text messages over twelve months after discharge following a suicidal + crisis, sent by a named team, supplementing usual care. +2. What it is not: not monitoring, not crisis response, not two-way, not automated risk assessment. +3. What is being asked: permission to run a small, governed pilot with one team — not a claim that it + works. + +Do not open the laptop before saying these. If the first thing they see is software, the conversation +becomes about software. + +## The path (about three and a half minutes) + +**Step 1 — A referral arrives.** Start on Today. Point at `Referrals to review` at the top. Say the order +is by discharge and contact timing, never by inferred risk, because the system does not assess risk. Ten +seconds, not thirty. + +**Step 2 — Confirm the person.** Open the referral. Show the identity step and the two gates: agreement +confirmed, and the explicit flag that the mobile is the patient's own and suitable for discreet contact. +Say plainly that without both, activation is blocked. This is the moment that demonstrates the safety +posture better than any other. + +**Step 3 — Choose the pathway and personalise.** Show the twelve-month cadence, the preferred name, the +team identity and the coordinator signature. Emphasise that there is no free typing — everything is chosen +from approved content. Show the message preview on a phone-sized frame. + +**Step 4 — Review and activate.** Show the exact dates, the send window, the two-segment evidence and the +one-way boundary. Show the first-contact date defaulting to the day after discharge, and say why: the +first message should not arrive while the person is still leaving the hospital. + +**Step 5 — Jump forward six months.** Use the demo clock. This is the single most persuasive moment +available — it turns an idea into an operating service. Show the schedule filled in, contacts delivered, +the plan mid-life. + +**Step 6 — Something goes wrong.** Open a permanent delivery failure. Show that it paused future contacts, +raised a same-day task with a named owner, and explains in plain words why it paused and what would change +it. Say that a failure is never allowed to be silent. + +**Step 7 — Someone wants to stop.** Withdraw a patient. Show that it is immediate, needs no approval, +cancels everything unsent, and keeps the history. + +**Step 8 — The ending.** Show the month-twelve closing message. Say that ending a year of contact without +naming the ending was a design flaw that was corrected. + +## Close (one minute) + +**Show the safety stop.** One control that halts every message to every patient across the whole service, +and requires three named people to restart. Say: this exists because a pilot that cannot be stopped in +seconds should not start. + +**Then the ask.** Be specific about what is wanted: a sponsoring team, a route into privacy and records +review, and a conversation with whoever owns the hospital referral feed. Not "what do you think". + +## Questions to have an answer ready for + +- _What if someone replies?_ They get an immediate automated message pointing to the staffed line and + crisis support. Nobody reads the reply and it is not stored. +- _Does this reduce suicide?_ Unknown, and not what the pilot would show. The evidence is mixed and the + proposal is an operational safety pilot. Have the [evidence brief](evidence-brief.md) to hand. +- _Where does the data live?_ Australian region, separate from everything else, with a retention policy + a records officer sets. Be honest that the hosting for a real pilot is unresolved. +- _Who is clinically accountable?_ Currently nobody — that is part of the ask. Do not bluff this. +- _Does it reach Aboriginal patients?_ The system reports reach in aggregate. A culturally appropriate + pathway is separate work requiring Aboriginal health leadership, and has not been done. +- _Who built this?_ One psychiatrist, with governance documents, a hazard log and a full test suite. + Say it plainly; it is a strength as long as the limits are stated. + +## What not to do + +- Do not show the pathway editor, reconciliation, the auditor trail or reporting. They exist, they matter + for governance, and they are not the story. +- Do not demonstrate on a phone unless asked — the coordinator workflow is a desktop task. +- Do not claim effectiveness, even softly. One overstated sentence undoes the credibility the rest of the + documentation buys. +- Do not exceed five minutes before pausing for questions. diff --git a/docs/caring-contacts/evidence-brief.md b/docs/caring-contacts/evidence-brief.md new file mode 100644 index 000000000..eabd6a1c4 --- /dev/null +++ b/docs/caring-contacts/evidence-brief.md @@ -0,0 +1,81 @@ +# Caring Contacts — evidence brief + +**Status:** draft, 19 August 2026. **Citations are unverified.** The studies below are named from general +knowledge and have **not** been checked against source in the session that produced this document. Verify +every citation, and never quote an effect size from this file, before it goes to a sponsor, a governance +board or an ethics committee. A wrong citation in a suicide-prevention proposal costs more credibility +than having no citation at all. + +**Audience.** A clinical director, service manager or governance board deciding whether to sponsor a pilot. +Not an engineering document. + +--- + +## What is being proposed + +Brief, non-demanding, one-way supportive messages sent to patients over twelve months after discharge +following a suicidal crisis. The messages carry no assessment, no question requiring an answer, no advice +and no monitoring. They supplement usual care; they do not replace follow-up by a person. + +## What the evidence supports + +The intervention has a long history and a plausible mechanism — sustained, low-burden connectedness after +a crisis, without placing a demand on the recipient. + +- **Motto & Bostrom (2001), _Psychiatric Services_.** The originating trial: letters to patients who + declined ongoing care after a psychiatric hospitalisation in San Francisco. Reported a lower suicide rate + in the contacted group in the early follow-up years. This is the study the whole field rests on, and it + is old, single-site, and of its era methodologically. +- **Carter et al. (2005), _BMJ_, "Postcards from the EDge".** The most directly relevant Australian trial — + postcards after hospital-treated deliberate self-poisoning in the Hunter region, NSW. Reported fewer + repeat episodes, while the proportion of individuals who repeated was not significantly different. The + distinction matters and is easy to overstate in either direction. Longer follow-up was published later. +- **Comtois et al. (2019), _JAMA Psychiatry_.** A caring-contacts trial using text messages in US military + personnel — the closest modern analogue to what is proposed here, and the reason SMS rather than + postcards is defensible. + +## What the evidence does not establish + +This section is the one that earns trust. A governance board will find these papers whether or not the +proposal cites them. + +- **Meta-analyses have been equivocal.** Milner et al. (2015), _British Journal of Psychiatry_, pooled brief + contact interventions — letters, postcards, green cards, telephone calls — and did not find a reduction in + the proportion of people who repeated self-harm, though findings on repetition events were more + favourable. Any proposal claiming brief contact "prevents suicide" is overstating the literature. +- **Individual trials have been null.** Replications, including in New Zealand, have failed to reproduce the + original effect. The evidence base is genuinely mixed rather than uniformly supportive. +- **SMS-specific evidence is thin.** Most of the evidence concerns postcards and letters. Whether the effect + transfers to text messages, and whether text is experienced as more or less personal, is not settled. +- **No trial establishes an optimal schedule.** The twelve-month, ten-contact cadence in this design is + labelled illustrative and locally governed for exactly that reason. It is not a validated protocol. +- **Nothing here supports a claim of lives saved.** No pilot of this size in one team could detect a + mortality effect, and proposing one would be a design error. + +## What this pilot would and would not demonstrate + +**Would:** whether the service can be operated safely by a real team; whether messages reach the right +person at the right time without duplication; whether exceptions, withdrawal, readmission and death are +handled correctly; whether clinicians can use it without error; and whether patients find it acceptable, +measured through a separately consented evaluation outside the system. + +**Would not:** clinical effectiveness, reduced self-harm, reduced admission, or reduced suicide. Those +require a trial, not a pilot. + +This framing is deliberate and protective. An operational safety pilot is approvable. An effectiveness +claim invites a demand for evidence the pilot cannot produce. + +## The honest summary for a sponsor + +Caring contacts is a low-cost, low-burden, well-tolerated intervention with a plausible mechanism, an +encouraging founding trial, a directly relevant Australian trial, and a mixed meta-analytic picture. It is +not a proven suicide-prevention treatment. What is being asked for is permission to demonstrate that it can +be delivered safely and acceptably by one team, under governance, with strict stopping rules — not +permission to claim it works. + +## What is missing from this brief + +- Verified citations, including volume, page and DOI. +- WA-specific context: local self-harm re-presentation rates and current aftercare provision. +- Cost: SMS is a few cents per message, so the real figures are hosting, support and clinician time. +- Any existing WA Health or national aftercare programme this would overlap with or complement. diff --git a/docs/caring-contacts/hazard-log.md b/docs/caring-contacts/hazard-log.md new file mode 100644 index 000000000..0ce4beca4 --- /dev/null +++ b/docs/caring-contacts/hazard-log.md @@ -0,0 +1,82 @@ +# Caring Contacts clinical hazard log + +**Status:** draft, 19 August 2026. Authored from the approved decision lock and design specifications. +**Not clinically approved.** No named clinical safety officer exists yet — see H-00. + +**Purpose.** Health software touching suicide risk is expected to carry an explicit hazard register: what +can go wrong, how badly, what makes it less likely, and who owns it. The raw material already existed +across the decision lock and design spec; this document assembles it into the form a clinical governance +board, a privacy officer or a clinical safety officer will ask for by name. + +**How to read severity.** `Catastrophic` — could contribute to death or serious harm. `Major` — significant +distress, privacy breach, or loss of trust in the service. `Moderate` — operational failure with a +recoverable clinical consequence. `Minor` — inconvenience or rework. + +**How to read status.** `Designed` — a control exists in the approved design. `Partial` — a control exists +but does not fully close the hazard. `Open` — no control yet; owner named. + +--- + +## Governance + +| ID | Hazard | Severity | Controls | Status | Owner | +| ---- | ----------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | --------------------------------- | +| H-00 | No named clinical safety officer, so no single person owns clinical risk for the service | Major | This log; the pre-pilot gate register in the production build spec §14 | **Open** | Josh, then the sponsoring service | +| H-01 | The service is mistaken for monitoring, crisis response or treatment, and a patient or clinician relies on it during a crisis | Catastrophic | Every message states the one-way boundary and names crisis support; prohibited-language list forbids reassurance and outcome claims; delivery states are transport-only and never patient-state labels | Designed | Clinical programme lead | +| H-02 | Delivery status is read as evidence of safety or wellbeing | Major | Closed transport vocabulary; "Delivered" carries a transport-only qualification wherever clinical ambiguity could arise; reports never infer patient state | Designed | Clinical programme lead | +| H-03 | Message content drifts from approved wording through local editing | Major | Structured personalisation only; no free text; `validateGovernedMessage` blocks prohibited content; immutable pathway/message version snapshots per active plan | Designed | Clinical programme lead | +| H-04 | Message content has never been reviewed by people with lived experience | Major | Dual approval required for every pathway version; lived-experience approval is a named gate at message content, complete prototype and pilot findings | **Open** — no review has occurred | Josh | +| H-05 | Content is not culturally safe for Aboriginal and Torres Strait Islander patients | Catastrophic | Aggregate reach reporting makes under-reach visible; a culturally appropriate pathway is explicitly separate approved work | **Open** — no Aboriginal health review has occurred | Aboriginal health governance | + +## Patient-facing + +| ID | Hazard | Severity | Controls | Status | Owner | +| ---- | ------------------------------------------------------------------------------------------------------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------- | +| H-10 | A distressed patient replies and receives silence | Catastrophic | Production build spec §2.1: receiving-capable number with an immediate automated response naming the programme line, crisis support and emergency direction; inbound content discarded and never stored | Designed | Clinical programme lead + provider | +| H-11 | A year of contact ends abruptly with no signal, and is experienced as being dropped | Major | Production build spec §2.2: a governed `closing` message at month 12 naming the ending and repeating where to get help | Designed | Clinical programme lead | +| H-12 | The first message arrives so soon after discharge that it feels automated or intrusive | Moderate | Production build spec §2.3: coordinator-set first contact date, defaulting to the day after discharge, bounded to discharge day +7, reason required to move | Designed | Coordinating clinician | +| H-13 | A message reaches the wrong person and discloses mental-health contact | Catastrophic | Source-system patient-controlled-mobile flag required before activation; discreet sender and wording that never expose suicide, crisis or mental-health treatment on a lock screen; a source number change pauses future contacts | Partial — no runbook exists for a wrong recipient who makes contact | Service | +| H-14 | A message arrives at or after the patient's death | Catastrophic | A recorded death irreversibly cancels all unsent contacts; third-party report allows immediate pause ahead of the record (§2.4) | Partial — notification of the coordinator and team support are unspecified | Clinical programme lead | +| H-15 | The service reaches only the least marginalised patients, because eligibility requires a patient-controlled mobile | Major | None. This is an accepted design consequence | **Open** — state explicitly in the governance submission | Josh | +| H-16 | A controlling family member ends a service the patient chose | Major | Third parties may pause only; permanent withdrawal requires the patient or the source system (§2.4) | Designed | Coordinating clinician | +| H-17 | Messages continue after a patient asks a family member to stop them, because records lag | Moderate | Any authorised team member may pause immediately on a third-party request, with requester and relationship recorded | Designed | Coordinating clinician | + +## Scheduling and delivery + +| ID | Hazard | Severity | Controls | Status | Owner | +| ---- | --------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------- | +| H-20 | A duplicate message is sent | Major | Idempotency keys on every write; lease-fenced dispatch; unique constraints preventing duplicate contact dispatch; twelve-month simulation proving zero duplicates under retry and concurrency | Designed | Technical owner | +| H-21 | A missed message is sent late, arriving out of context | Moderate | Missed contacts are recorded and never sent retrospectively; the calendar never rebases; provider-outage contacts are marked missed | Designed | Technical owner | +| H-22 | A message sends outside safe hours | Moderate | Sending confined to 09:00–18:00 AWST; windows fixed at 10:00, 14:00 and 17:00; retries strictly inside the original window | Designed | Technical owner | +| H-23 | A failed delivery is never noticed | Major | Permanent failure pauses future contacts and raises a same-day operational task; exception ownership and resolution age are visible; unclaimed work escalates to team lead after 60 minutes | Designed | Team lead | +| H-24 | Transport status is wrong after a provider outage and a contact is resent to an uncertain recipient | Major | Manual reconciliation screen; uncertain contacts are never resent automatically | Designed | Service + technical owner | +| H-25 | A patient is enrolled twice and receives duplicate pathways | Major | A duplicate referral for an active plan is blocked and routed to the existing episode; a later qualifying discharge creates a new linked episode without mutating the earlier one | Designed | Technical owner | + +## Privacy and access + +| ID | Hazard | Severity | Controls | Status | Owner | +| ---- | ---------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------- | +| H-30 | Patient data reaches the Clinical KB search, retrieval or model paths | Catastrophic | Enforced module seam with an import-isolation test; a dedicated database project separate from the Clinical KB project; a check asserting caring-contact configuration never resolves to the pinned Clinical KB reference | Designed | Technical owner | +| H-31 | Patient data appears in logs, URLs, page titles, alerts or screenshots | Major | Redaction contracts; identifier-free external alerts; synthetic identities in all prototype and test captures; static and request-level tests | Designed | Technical owner | +| H-32 | A clinician sees patients outside their team | Major | Deny-by-default, team-scoped permissions enforced in the database as well as the application; every denial returns a named reason | Designed | Technical owner | +| H-33 | Audit history is lost, so what was sent cannot later be established | Catastrophic | Audit rows written in the same transaction as the change; de-identification preserves actor, action, timestamp, object type and outcome | Designed | Technical owner | +| H-34 | Patient data is retained indefinitely with no lawful basis | Major | Retention is a configured policy value with genuine erasure built in; working assumption seven years | Partial — the real figure is unset | Records officer | +| H-35 | Inbound reply content is retained at the provider despite the non-persistence rule | Major | Provider adapter contract requires auto-response with non-persistence; privacy review must confirm the position | **Open** — privacy review has not occurred | Privacy review | +| H-36 | Patient data is processed or stored outside Australia | Catastrophic | Australian-region requirement for data, backups, logs and provider processing; Sydney region for the dedicated database | Partial — the current application tier has no Australian region available | Josh, then the sponsoring service | + +## Operational + +| ID | Hazard | Severity | Controls | Status | Owner | +| ---- | --------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------------------- | +| H-40 | An incident continues because no one can stop the service quickly | Catastrophic | Service safety stop halting all sending across every patient and team; restart requires three named approvals | Designed | Incident lead | +| H-41 | An unassessed clinician operates the service and mishandles withdrawal, death or a delivery failure | Major | Training mode with assessed simulation of the seven required competencies before production access | Designed | Team lead | +| H-42 | Workload exceeds the team's capacity because the pilot has no numeric cap | Major | Continuous queue-age and workload monitoring; automatic stopping rules; 6–8-week early governance review | Designed | Team lead | +| H-43 | Coordinators carry cumulative distress from a suicide-aftercare caseload | Major | None | **Open** — no supervision model exists | Clinical programme lead | +| H-44 | The referral feed from the hospital system cannot be built, after the workspace is complete | Moderate (programme, not patient) | Provider-neutral referral interface with a synthetic adapter, so the build is not blocked | Partial — feasibility unconfirmed | Josh | + +--- + +## Open hazards requiring action before any real patient + +H-00, H-04, H-05, H-15, H-35, H-43 are unmitigated. H-13, H-14, H-34, H-36 and H-44 are partially +mitigated. None blocks the synthetic build; all block a pilot. diff --git a/docs/caring-contacts/message-review-pack.md b/docs/caring-contacts/message-review-pack.md new file mode 100644 index 000000000..2778e5752 --- /dev/null +++ b/docs/caring-contacts/message-review-pack.md @@ -0,0 +1,101 @@ +# Message review pack — lived experience and clinical + +**Status:** ready to run, 19 August 2026. Owner: Josh. Hazard **H-04**. + +**Why.** The message text is the highest-risk content in the programme and the cheapest thing to get +wrong. It has never been read by anyone with lived experience of a suicidal crisis. Doing this costs an +afternoon and should happen **before** the system is shown to a sponsor — a demonstration built around +wording that reads as automated is worse than no demonstration. + +**Who.** Three or four people with lived experience of a suicidal crisis or a hospital discharge after +one, plus a clinician who is not part of designing this. Paid or otherwise properly recognised, per +normal lived-experience engagement practice. No patients currently under the reviewer's care. + +**What this review is not.** Not consent, not ethics approval, not a substitute for the formal +lived-experience approval gate at pathway-version level. It is early formative feedback that will shape +what goes to that gate. + +--- + +## 1. A correction that must be made first + +The reply decision of 19 August (production build specification §2.1) changed what happens when someone +replies: messages now come from a number that can receive, an automated response is sent immediately, and +the reply content is discarded without ever being stored or read. + +The current message text says: + +> Replies are not received, stored, analysed or monitored + +Under the new design the first clause is **no longer true** — replies are received by the number, then +discarded. Continuing to use this wording would be telling patients something inaccurate about a safety +boundary, which is precisely the kind of error this programme cannot afford. + +The replacement wording is a clinical decision, not an engineering one, and is the first thing this review +should settle. The requirement is that it be **true**, **plain**, and **not discouraging** to someone who +is struggling. Candidate direction, for the group to react to rather than adopt: something conveying that +nobody reads replies to this number, followed immediately by where someone _is_ available. + +## 2. The current message, in full + +The approved patient-visible text as it stands, with fictional details: + +> Hi Rowan, Alex from Example Aftercare Team is thinking of you. This is a one-way message. Replies are not +> received, stored, analysed or monitored. For timing changes call \, 9 am–6 pm. In an +> emergency call 000. Fictional Support Line: \. — Alex + +This is the **first** message, which by policy carries the complete support information. Later messages +keep a short boundary statement and the programme contact, and are correspondingly shorter. Every message +including notices and signature must fit two SMS segments. + +## 3. What to ask + +Show the message on a phone screen, not on paper, and not in a spreadsheet. Show it as it would arrive. + +**First impressions** + +1. What is your honest first reaction to receiving this two days after leaving hospital? +2. Does it feel like it came from a person or from a system? What makes the difference? +3. Would you know who it was from? + +**The boundary** + +4. What do you understand about whether you can reply? +5. If you were having a bad night and texted back, what would you expect to happen? +6. Does the boundary wording feel like care, or like being kept at arm's length? Where is the line? + +**The practicalities** + +7. Is it clear where to get help, and which number is for what? +8. Is there anything here you would not want visible on a lock screen? +9. Is the length right — too much, too little? + +**Over time** + +10. How would you feel receiving these ten times over a year? +11. How should the last one, at twelve months, be different? What would make the ending feel considered + rather than abrupt? +12. What would make you want them to stop? + +**The name** + +13. The service is called Caring Contacts. Does that name set the right expectation? Does anything about it + promise something it should not? + +## 4. What to record + +For each question: what was said, in their words rather than paraphrased into clinical language. +Separately, a short list of **changes required** versus **changes suggested**, because the first group +blocks progress and the second does not. + +Anything raised that is not about wording — timing, frequency, who sends it, what happens at the end — +belongs in the hazard log or the decision register, not lost in a wording note. + +## 5. What happens to the output + +1. Required changes are made to the message set. +2. The corrected reply-boundary wording (§1) is settled and the constant updated in code. +3. Findings that change policy rather than wording become dated decision-lock revisions. +4. The revised set goes to the formal dual approval — clinical programme lead plus lived-experience + representative — which is a separate, recorded gate. +5. Only then is the message set used in any demonstration. diff --git a/docs/caring-contacts/referral-feasibility.md b/docs/caring-contacts/referral-feasibility.md new file mode 100644 index 000000000..c8cadbb18 --- /dev/null +++ b/docs/caring-contacts/referral-feasibility.md @@ -0,0 +1,87 @@ +# Referral feed feasibility — the questions to ask, and who to ask + +**Status:** open, 19 August 2026. Owner: Josh, then a sponsoring service. + +**Why this document exists.** Every screen, rule and database table in this programme assumes a structured +referral arrives from a hospital system and a structured outcome is written back. No document names an +actual Western Australian system, and nobody has confirmed the feed is possible, who owns it, or what it +costs. This is the largest single risk to the programme and it is not a software risk — the build itself +is insulated, because it runs against a provider-neutral referral interface with a synthetic adapter +(hazard **H-44**). + +The purpose of this document is to make one conversation productive. It is not a technical integration +spec. + +## What the service needs to receive + +The minimum structured referral, per the approved decision lock: + +| Field | Why it is needed | Failure if absent | +| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------- | +| Patient identity from the source system | Identity confirmation before enrolment | Manual re-entry, transcription error | +| Adult status | Objective eligibility | Ineligible enrolment | +| Qualifying discharge, with actual discharge date and time | The entire schedule is anchored to it | No schedule can be built | +| Mobile number | Delivery | No delivery | +| **An explicit flag that the mobile is patient-controlled and suitable for discreet SMS** | Prevents messages reaching family, carers or shared handsets | Hazard H-13, the most serious privacy failure in the design | +| Agreement confirmed, yes or no | Activation gate | Cannot activate | +| Referring clinician and team | Ownership until acceptance | Ownership ambiguity | +| Aboriginal and Torres Strait Islander status | Aggregate reach reporting only | Cannot answer the equity question | + +The patient-controlled-mobile flag is the field most likely not to exist. A plain mobile-number field is +explicitly insufficient. If the source system cannot supply it, the enrolment process must capture it +another way, and that changes the clinical workflow rather than the software. + +## What the service needs to send back + +Structured write-back on referral outcome, activation, pause, withdrawal, cancellation, material delivery +exception and completion. Detailed transport and access evidence stays in Caring Contacts and does not go +to the record. + +## Questions to ask + +**About the system** + +1. Which system holds emergency-department and inpatient mental-health discharges for the candidate + service, and which one would originate a referral? +2. Does it support outbound structured referrals to an external service, and by what mechanism? +3. Can it accept structured write-back, or is the only route a free-text progress note? +4. Is there an existing integration pattern for an external follow-up service, or would this be the first? + +**About the data** + +5. Is there a field recording that a mobile number is patient-controlled and suitable for discreet + contact? If not, what would it take to add one, or where else could it be captured? +6. Is discharge date **and time** available, or date only? The schedule anchors to actual discharge time. +7. Is Aboriginal and Torres Strait Islander status available in a form that can be transmitted? + +**About ownership and permission** + +8. Who owns the integration decision — the health service, a statewide digital health function, or both? +9. What approval is required before any external system receives patient identifiers: privacy impact + assessment, information-sharing agreement, security assessment, procurement? +10. Roughly how long does that take, and does it need a sponsoring executive before it can start? + +**About cost and effort** + +11. Is integration work charged to the requesting service, and is there a rough order of magnitude? +12. Is there a queue, and what does joining it require? + +## Who to ask + +In rough order of usefulness: a digital health or clinical informatics lead in the candidate health +service; the mental-health service manager who would sponsor the pilot; anyone who has recently taken an +external clinical system live in the same service, because they will know the real path rather than the +documented one. + +## What a bad answer means + +If a structured feed is not achievable in a reasonable timeframe, the programme is not dead — but the +first pilot becomes **manual referral entry by the aftercare team** from the existing discharge process, +with write-back as a progress note. That is a genuine fallback: it changes workload and the identity +confirmation step, not the clinical model. It should be designed deliberately rather than discovered late. + +## What to do with the answers + +Record them here, then update the production build specification's open register and this programme's +hazard **H-44**. If manual entry becomes the pilot route, that is a decision-lock revision and needs +writing up as one. diff --git a/docs/outstanding-issues-inbox/0f9238c1-8add-450c-92d1-917376761248.json b/docs/outstanding-issues-inbox/0f9238c1-8add-450c-92d1-917376761248.json new file mode 100644 index 000000000..e0cd93293 --- /dev/null +++ b/docs/outstanding-issues-inbox/0f9238c1-8add-450c-92d1-917376761248.json @@ -0,0 +1,14 @@ +{ + "version": 2, + "id": "0f9238c1-8add-450c-92d1-917376761248", + "createdOn": "2026-08-18", + "action": "add", + "payload": { + "pri": "P1", + "type": "issue", + "summary": "Caring Contacts patient-visible reply wording is now factually wrong and must change before any demonstration", + "detail": "The 2026-08-19 decision revision (production build spec 2.1) changed replies from a non-receiving sender to a receiving-capable number that auto-responds and discards. PATIENT_VISIBLE_NO_REPLY_NOTICE in src/components/caring-contacts/mockups/personalisation-screen.tsx still reads 'Replies are not received, stored, analysed or monitored'. The first clause is no longer true: replies ARE received by the number, then discarded unread. Telling patients something inaccurate about a safety boundary is exactly the failure this programme cannot afford. Replacement wording is a clinical decision requiring dual approval, and is the first item in docs/caring-contacts/message-review-pack.md.", + "source": "Production build spec 2.1; message review pack section 1", + "issueUlid": "01M0B6TQ332YXE61JXSY5AYNX0" + } +} diff --git a/docs/outstanding-issues-inbox/6a617628-6b65-4f7f-b361-f96da2d0880a.json b/docs/outstanding-issues-inbox/6a617628-6b65-4f7f-b361-f96da2d0880a.json new file mode 100644 index 000000000..036d93a01 --- /dev/null +++ b/docs/outstanding-issues-inbox/6a617628-6b65-4f7f-b361-f96da2d0880a.json @@ -0,0 +1,14 @@ +{ + "version": 2, + "id": "6a617628-6b65-4f7f-b361-f96da2d0880a", + "createdOn": "2026-08-18", + "action": "add", + "payload": { + "pri": "P2", + "type": "issue", + "summary": "Railway has no Australian region, so the current app tier cannot host a real-patient Caring Contacts deployment", + "detail": "docs/deployment-architecture.md records Railway regions as US West, US East, Amsterdam and Singapore; the app tier runs in Singapore against Supabase in ap-southeast-2 Sydney. The Caring Contacts decision lock requires identifiers, message content, application data, backups, logs and provider processing to remain in Australia. A real-patient pilot therefore needs a separately contracted Australian PHI-capable environment, not the current Clinical KB deployment. Does not block the synthetic build, which holds no real patient data. Hazard H-36.", + "source": "docs/deployment-architecture.md; Caring Contacts decision lock hosting controls", + "issueUlid": "01M0B6WFEPNCAWAFRW03H3WSDY" + } +} diff --git a/docs/outstanding-issues-inbox/73810780-d91c-403f-96ab-e659a75c8688.json b/docs/outstanding-issues-inbox/73810780-d91c-403f-96ab-e659a75c8688.json new file mode 100644 index 000000000..73d290af1 --- /dev/null +++ b/docs/outstanding-issues-inbox/73810780-d91c-403f-96ab-e659a75c8688.json @@ -0,0 +1,14 @@ +{ + "version": 2, + "id": "73810780-d91c-403f-96ab-e659a75c8688", + "createdOn": "2026-08-18", + "action": "add", + "payload": { + "pri": "P2", + "type": "task", + "summary": "Caring Contacts hospital referral feed feasibility is unconfirmed and is the largest programme risk", + "detail": "Every screen, rule and table assumes a structured referral arrives from a WA hospital system and a structured outcome is written back. No document names an actual system; nobody has confirmed the feed is possible, who owns it, or what it costs. The build is insulated by a provider-neutral referral interface with a synthetic adapter, so this does not block development. docs/caring-contacts/referral-feasibility.md holds the twelve questions to ask, who to ask, and the manual-entry fallback if a structured feed is not achievable. Hazard H-44. One conversation with a WA Health clinical informatics lead is worth more than a month of code.", + "source": "Caring Contacts design session 2026-08-19; hazard log H-44", + "issueUlid": "01M0B6VK0YTDKW4WDTWF4T8VN1" + } +} diff --git a/docs/outstanding-issues-inbox/82838fb1-7ed2-4f37-bd50-191a603ecd0f.json b/docs/outstanding-issues-inbox/82838fb1-7ed2-4f37-bd50-191a603ecd0f.json new file mode 100644 index 000000000..c00e7029e --- /dev/null +++ b/docs/outstanding-issues-inbox/82838fb1-7ed2-4f37-bd50-191a603ecd0f.json @@ -0,0 +1,14 @@ +{ + "version": 2, + "id": "82838fb1-7ed2-4f37-bd50-191a603ecd0f", + "createdOn": "2026-08-18", + "action": "add", + "payload": { + "pri": "P3", + "type": "issue", + "summary": "docs:check-links passes over a broken relative markdown link in a spec, so a binding document went missing unnoticed", + "detail": "scripts/check-docs-links.mjs reported 1905 references resolving while docs/superpowers/specs/2026-08-15-caring-contact-coordination-design.md line 180 linked to ../../caring-contacts/design-handoff.md, a file that has never existed, and line 131 described it as binding. Found by hand on 2026-08-19 and repointed to interaction-matrix.md, which actually holds the 24-row modality matrix. The gate is a check that cannot fail for this class of link: verify whether relative markdown links outside a recognised prefix are skipped, and close the gap. Same family as the mutation-testing concerns already recorded for stderr hooks and tail-masked exit codes.", + "source": "Caring Contacts doc repair 2026-08-19", + "issueUlid": "01M0B6WNK5ZM8902PCKT80QZPA" + } +} diff --git a/docs/outstanding-issues-inbox/ba2bdfba-b1e1-4e13-83b4-8cb0f3ddc092.json b/docs/outstanding-issues-inbox/ba2bdfba-b1e1-4e13-83b4-8cb0f3ddc092.json new file mode 100644 index 000000000..8e8e850fd --- /dev/null +++ b/docs/outstanding-issues-inbox/ba2bdfba-b1e1-4e13-83b4-8cb0f3ddc092.json @@ -0,0 +1,14 @@ +{ + "version": 2, + "id": "ba2bdfba-b1e1-4e13-83b4-8cb0f3ddc092", + "createdOn": "2026-08-18", + "action": "add", + "payload": { + "pri": "P1", + "type": "task", + "summary": "Caring Contacts: three unmitigated hazards block any real-patient pilot (safety officer, lived-experience review, Aboriginal health review)", + "detail": "docs/caring-contacts/hazard-log.md records H-00 (no named clinical safety officer, so nobody owns clinical risk), H-04 (the message set has never been read by anyone with lived experience) and H-05 (no Aboriginal cultural safety review, in a WA suicide-aftercare service). All three are Open with no control. None blocks the synthetic build; every one blocks a pilot. H-04 is ready to run today: docs/caring-contacts/message-review-pack.md is a complete facilitation pack. Owner Josh for H-00 and H-04; Aboriginal health governance for H-05.", + "source": "Caring Contacts design session 2026-08-19; hazard log H-00/H-04/H-05", + "issueUlid": "01M0B6SSW31S81R85ACX1CVPHG" + } +} diff --git a/docs/outstanding-issues-inbox/ebf42f52-3e74-484f-81cd-ebcbd4954b10.json b/docs/outstanding-issues-inbox/ebf42f52-3e74-484f-81cd-ebcbd4954b10.json new file mode 100644 index 000000000..2b739b71d --- /dev/null +++ b/docs/outstanding-issues-inbox/ebf42f52-3e74-484f-81cd-ebcbd4954b10.json @@ -0,0 +1,14 @@ +{ + "version": 2, + "id": "ebf42f52-3e74-484f-81cd-ebcbd4954b10", + "createdOn": "2026-08-18", + "action": "add", + "payload": { + "pri": "P2", + "type": "task", + "summary": "Caring Contacts synthetic production build: spec approved and committed, implementation plan not yet written", + "detail": "docs/superpowers/specs/2026-08-19-caring-contact-production-build-design.md is the binding spec: ten decision-lock revisions, the sealed domain rules layer, a dedicated Supabase project hard-separated from the Clinical KB project, seven screens required by existing decisions but never designed, four recommended screens, the design non-regression contract and the elevation brief. Delivery is two pull requests with subagent-driven development: (1) rules plus datastore plus doc repairs, (2) screens plus demo clock, synthetic caseload and training mode. Next step is the writing-plans skill to produce the implementation plan for part one. Design phase itself is complete and merged (PR #2095, #2133).", + "source": "Caring Contacts design session 2026-08-19", + "issueUlid": "01M0B6VQJC4STSM1XD22Y0XPWJ" + } +} diff --git a/docs/superpowers/plans/2026-08-14-caring-contact-coordination-rollout.md b/docs/superpowers/plans/2026-08-14-caring-contact-coordination-rollout.md index a56d2be48..ed6fcb95a 100644 --- a/docs/superpowers/plans/2026-08-14-caring-contact-coordination-rollout.md +++ b/docs/superpowers/plans/2026-08-14-caring-contact-coordination-rollout.md @@ -36,22 +36,22 @@ These decisions refine the approved concept and must not be reopened during rout ### Service, referral and ownership model - The first real-patient pilot serves one dedicated hospital aftercare/transition team at one hospital/service. It is not a statewide or multi-health-service tenancy pilot. -- The discharging clinician confirms the source-system identity, mobile information and verbal agreement. The existing hospital record/referral workflow sends a structured referral to Callback. +- The discharging clinician confirms the source-system identity, mobile information and verbal agreement. The existing hospital record/referral workflow sends a structured referral to Caring Contacts. - The dedicated aftercare team reviews, personalises, activates and owns the caring-contact plan for its full duration. - New referrals appear first on Today in `Referrals to review`, ordered by discharge and first eligible contact-window timing, never inferred clinical risk. - The aftercare team may accept, return for clarification or decline using structured reasons. Clarification and decline write back to the hospital referral system, which owns referrer notification. -- The referring team retains responsibility until explicit acceptance. Callback must not imply that a pending or returned referral has transferred ownership. +- The referring team retains responsibility until explicit acceptance. Caring Contacts must not imply that a pending or returned referral has transferred ownership. - Accepted referrals enter the team queue and require an explicit coordinator claim or team-lead assignment. There is no automatic round-robin assignment. - Authorised teammates provide audited coverage during coordinator absence; the named coordinator and any formal reassignment remain visible. - Eligibility uses objective prerequisites only: adult status, qualifying discharge/referral, pilot-service scope, patient-controlled mobile flag and agreement. Diagnosis, presentation details and risk assessments never drive automated eligibility. -- Search is restricted to referrals and caring-contact episodes belonging to the pilot team. Callback is not a hospital-wide patient directory. +- Search is restricted to referrals and caring-contact episodes belonging to the pilot team. Caring Contacts is not a hospital-wide patient directory. ### Mobile, agreement and patient control -- Callback imports the current hospital-record mobile number without test SMS, verbal read-back or separate referrer attestation. +- Caring Contacts imports the current hospital-record mobile number without test SMS, verbal read-back or separate referrer attestation. - Activation nevertheless requires an explicit source-system flag that the destination is patient-controlled and suitable for discreet SMS. A plain mobile-number field is insufficient. Family, carer and shared destinations are ineligible. -- The agreement interface is a simple `Agreement confirmed: Yes/No`. The audit automatically retains the source referral, referring clinician and received timestamp; no separate Callback agreement ceremony is added. -- A source-system mobile-number change automatically pauses future contacts and creates a coordinator-review exception. Callback never silently switches the destination. +- The agreement interface is a simple `Agreement confirmed: Yes/No`. The audit automatically retains the source referral, referring clinician and received timestamp; no separate Caring Contacts agreement ceremony is added. +- A source-system mobile-number change automatically pauses future contacts and creates a coordinator-review exception. Caring Contacts never silently switches the destination. - Patients request timing changes, pause or withdrawal through the named programme phone. It is staffed seven days during every sending window, and any authorised team member can act immediately. - Withdrawal immediately cancels all unsent contacts, requires no approval, retains immutable history and writes back the milestone. A reason is optional. - A pause keeps the original discharge-anchored calendar. Contacts falling inside the pause are skipped permanently; explicit resumption begins with the next future contact. @@ -66,7 +66,7 @@ These decisions refine the approved concept and must not be reopened during rout - Personalisation is structured only: preferred name, neutral team identity, coordinator signature and approved message variants. There is no unrestricted clinician free text or dynamic translation. - The first pilot uses approved English content only. Interpreter-supported enrolment uses existing service processes; translated pathways require separate professional translation and cultural approval. - Patient-visible sender and message wording are discreet but recognisable and never expose suicide, crisis or mental-health treatment on a lock screen. -- Use a non-receiving sender. Callback receives, stores, analyses and displays no replies. +- Use a non-receiving sender. Caring Contacts receives, stores, analyses and displays no replies. - Enrolment and the first SMS provide complete support information. The first SMS includes the programme phone and hours, emergency direction and one approved crisis-support contact in plain text; later messages retain the short no-reply boundary and programme contact. - Every fully substituted message, including required notices and signature, is limited to two concatenated SMS segments. The UI shows encoding and exact segment count and blocks overflow. @@ -77,7 +77,7 @@ These decisions refine the approved concept and must not be reopened during rout - Hospital readmission automatically pauses future contacts. A later discharge requires a new linked referral and coordinator decision; the old episode never automatically resumes or rebases. - A recorded death immediately and irreversibly cancels all unsent contacts. A later source correction is an incident and requires a new referral for any future plan. - Completed, cancelled and withdrawn plans become read-only, leave active worklists and remain available for the formally approved retention period. -- Structured clinical-record write-back covers referral outcome, activation, pause, withdrawal, cancellation, material delivery exception and completion. Detailed transport and access evidence remains in Callback. +- Structured clinical-record write-back covers referral outcome, activation, pause, withdrawal, cancellation, material delivery exception and completion. Detailed transport and access evidence remains in Caring Contacts. - Transient transport failures receive two bounded application retries, for three attempts total, within the original window. The application never retries outside that window. - A permanent failure pauses future contacts and creates a same-day operational task. It never automatically triggers patient contact or clinical review. - Provider outage contacts that miss their window are marked missed and never sent late. Future cadence remains unchanged after restoration. @@ -87,9 +87,9 @@ These decisions refine the approved concept and must not be reopened during rout - A clinical programme lead and a lived-experience/content representative both approve new or materially changed pathway/message versions. Privacy or legal review joins when disclosure or agreement changes. - The pilot proves operational safety, reliability, clinician usability and patient acceptability. It is not a clinical-effectiveness study. -- Patient acceptability uses a separately consented evaluation process outside Callback, with aggregate reporting only. -- WA Health enterprise SSO/MFA and service-managed team groups control access. No Callback-local credentials exist. -- Any device may access Callback only when WA Health SSO/MFA, conditional access and managed-session controls succeed. No patient download or persistent browser-local patient storage is permitted. +- Patient acceptability uses a separately consented evaluation process outside Caring Contacts, with aggregate reporting only. +- WA Health enterprise SSO/MFA and service-managed team groups control access. No Caring Contacts-local credentials exist. +- Any device may access Caring Contacts only when WA Health SSO/MFA, conditional access and managed-session controls succeed. No patient download or persistent browser-local patient storage is permitted. - Enterprise policy controls session timeout. Activation, withdrawal, reassignment and any allowed export require fresh authentication. - The pilot permits no patient-level export. Approved aggregate reporting may include imported clinical-source demographic fields with a governance-configured small-cell threshold and a non-inferable `Suppressed` state. - Every patient search, view, decision, mutation, write-back and administrative access enters an immutable audit trail. Clinicians see episode-relevant operational history; privacy/security auditors see the complete access trail. @@ -108,7 +108,7 @@ These decisions refine the approved concept and must not be reopened during rout - The single-team pilot has no numeric patient cap and accepts every eligible referral while open. This is a conscious exposure choice; strict automatic stopping rules, workload monitoring and the 6–8-week early governance review are mandatory. - Production access requires assessed simulation of identity review, activation, withdrawal, delivery failure, readmission, downtime and incident handling. - Lived-experience approval is required at message-content, complete-prototype and pilot-findings gates, and may block progression. -- Go-live receives two weeks of seven-day hypercare with named clinical, service, technical, privacy and incident leads plus daily Callback queue/state review. Provider-side reconciliation remains event-triggered by outage, discrepancy or suspected incident. +- Go-live receives two weeks of seven-day hypercare with named clinical, service, technical, privacy and incident leads plus daily Caring Contacts queue/state review. Provider-side reconciliation remains event-triggered by outage, discrepancy or suspected incident. - Rollout remains sequential: approved design specification → complete synthetic prototype → secure datastore/tenancy → fake-provider simulation → authorised non-production provider → staged real-patient pilot. ### Approved visual direction @@ -124,13 +124,13 @@ These decisions refine the approved concept and must not be reopened during rout ## 1. Outcome and recommended direction -Build Callback as a **dedicated caring-contact workspace inside this codebase, with a separate operational shell and a separately approved runtime/data boundary**. +Build Caring Contacts as a **dedicated caring-contact workspace inside this codebase, with a separate operational shell and a separately approved runtime/data boundary**. That choice deliberately separates three things: 1. **Shared design language** — tokens, typography, controls, overlays, focus behaviour, accessibility, responsive states, iconography and quality gates come from Clinical KB. 2. **Dedicated product navigation** — Today, Patients, Schedule, Templates and More belong to caring-contact coordination, not to the global search composer or the thirteen reference modes. -3. **Patient-data boundary** — the current product and PIA assume no solicited patient-identifiable data. Callback cannot silently widen that assumption by adding a route to the existing RAG deployment. +3. **Patient-data boundary** — the current product and PIA assume no solicited patient-identifiable data. Caring Contacts cannot silently widen that assumption by adding a route to the existing RAG deployment. The memorable product signature is one restrained **continuity thread**: close early nodes that widen across the approved cadence. It is a schedule and continuity device only. It never changes colour or geometry based on clinical state, inferred risk, delivery success or patient behaviour. @@ -166,7 +166,7 @@ Use the repository's declared order, not historical preference: The repository's six canonical Linux baselines are human-approved hosted-CI artifacts recorded in `tests/__screenshots__/linux/provenance.json` and governed by `docs/design-system/adoption-contract.json`: -| Rendered surface | Evidence file | Callback lesson | +| Rendered surface | Evidence file | Caring Contacts lesson | | ------------------------ | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Dashboard shell, desktop | `tests/__screenshots__/linux/dashboard-shell.png` | Quiet centred hierarchy, one obvious command and minimal chrome. | | Dashboard shell, phone | `tests/__screenshots__/linux/dashboard-shell-phone.png` | Compact header, large reachable action and safe-area discipline. | @@ -194,9 +194,9 @@ The local app identity was also confirmed through `/api/local-project-id` as `Cl | Launcher entry | `src/lib/tools-catalog.ts`, `/tools` | Add one `coordination` destination after production-route approval. Do not add a searchable `AppModeId`. | | Route reachability | `docs/wiring-conventions.md`, `tests/route-reachability.test.ts` | Every production route has a real inbound path or a documented, tested exception. | -### 2.5 Components not to extend as Callback foundations +### 2.5 Components not to extend as Caring Contacts foundations -- `GlobalSearchShell`, `MasterSearchHeader` and the shared composer: Callback is patient-first, not query-first. +- `GlobalSearchShell`, `MasterSearchHeader` and the shared composer: Caring Contacts is patient-first, not query-first. - `app-modes.ts`: every current mode declares a search contract; caring-contact coordination is not a search result surface. - `patient-profile-storage.ts`: browser-local reference context is not an acceptable patient-plan datastore. - `AsyncButton`: deprecated; use `Button` busy state. @@ -206,20 +206,20 @@ The local app identity was also confirmed through `/api/local-project-id` as `Cl ### 2.6 Repository maturity conflict that changes the rollout -The existing product explicitly tells clinicians not to enter patient-identifiable information. Its current persistence is individual-owner scoped, and its PIA describes Clinical KB as a knowledge base rather than a patient record. Callback requires deliberate identity confirmation, mobile details, agreement, team ownership and longitudinal communication history. Therefore: +The existing product explicitly tells clinicians not to enter patient-identifiable information. Its current persistence is individual-owner scoped, and its PIA describes Clinical KB as a knowledge base rather than a patient record. Caring Contacts requires deliberate identity confirmation, mobile details, agreement, team ownership and longitudinal communication history. Therefore: - Design work can proceed in this repository with synthetic data. - Production code can proceed only behind a non-production feature boundary. - Real-patient use cannot proceed on the current deployment assumptions without a new privacy, security, records, tenancy and hosting decision. -- The current Railway/OpenAI RAG route is irrelevant to message generation and must not receive Callback data. +- The current Railway/OpenAI RAG route is irrelevant to message generation and must not receive Caring Contacts data. ## 3. WA clinical, service and evidence grounding ### 3.1 What the authoritative sources support - The WA Mental Health Commission announced an Aftercare Services Program on 15 June 2026 providing brief interventions, psychosocial support and care coordination for people discharged after a suicidal crisis. This supports the cohort and coordination context, not a particular SMS workflow: [Aftercare Services launched](https://www.mhc.wa.gov.au/news-and-resources/latest-news/aftercare-services-launched). -- WA guidance emphasises direct, coordinated post-discharge follow-up, documented clinician responsibility, collaborative discharge planning and local protocols. Callback must remain additive to these arrangements, never their substitute: [Principles and Best Practice for the Care of People Who May Be Suicidal](https://www.health.wa.gov.au/-/media/Files/Corporate/general-documents/Mental-health/PDF/Best-Practice-for-the-Care-of-People-Who-May-Be-Suicidal.pdf). -- NSQHS Action 5.32 requires follow-up arrangements to be developed, communicated and implemented. Callback may coordinate one bounded element of an approved follow-up plan but cannot claim to satisfy the standard by itself: [Comprehensive Care Standard](https://www.safetyandquality.gov.au/national-standards/nsqhs-standards/comprehensive-care-standard). +- WA guidance emphasises direct, coordinated post-discharge follow-up, documented clinician responsibility, collaborative discharge planning and local protocols. Caring Contacts must remain additive to these arrangements, never their substitute: [Principles and Best Practice for the Care of People Who May Be Suicidal](https://www.health.wa.gov.au/-/media/Files/Corporate/general-documents/Mental-health/PDF/Best-Practice-for-the-Care-of-People-Who-May-Be-Suicidal.pdf). +- NSQHS Action 5.32 requires follow-up arrangements to be developed, communicated and implemented. Caring Contacts may coordinate one bounded element of an approved follow-up plan but cannot claim to satisfy the standard by itself: [Comprehensive Care Standard](https://www.safetyandquality.gov.au/national-standards/nsqhs-standards/comprehensive-care-standard). - EMHS distinguishes clinically relevant community follow-up from administrative contact. Caring-contact delivery must not be counted as clinical follow-up unless the health service's measure owner explicitly defines it that way: [Community follow-up within seven days](https://emhs.health.wa.gov.au/Patient-Care/Safety-and-Quality/Mental-Health/Community-Follow-Up). - WA Health's consent policy requires collaborative, informed decision-making and consistent documentation. Local governance must decide how the caring-contact agreement maps to treatment consent, communication preference and the clinical record: [Consent to Treatment Policy](https://www.health.wa.gov.au/About-us/Policy-frameworks/Clinical-Governance-Safety-and-Quality/Mandatory-requirements/Consent-to-Treatment-Policy). - WA Health's Digital Health and Information Security policies make consumer consent, privacy, cyber security, confidentiality, integrity and availability mandatory design inputs: [Digital Health Policy Framework](https://www.health.wa.gov.au/about-us/policy-frameworks/digital-health), [Information Security Policy](https://www.health.wa.gov.au/about-us/policy-frameworks/digital-health/mandatory-requirements/information-security-policy). @@ -244,7 +244,7 @@ Every design and implementation review must reject copy or visuals that imply: ## 4. Repository-native approaches considered -### Approach A — add Callback as another shared search mode +### Approach A — add Caring Contacts as another shared search mode **Shape:** Extend `app-modes.ts`, `GlobalSearchShell` and the shared composer. @@ -266,7 +266,7 @@ Every design and implementation review must reject copy or visuals that imply: ### Approach C — separate application repository with copied design assets -**Shape:** Build Callback independently and manually mirror Clinical KB tokens/components. +**Shape:** Build Caring Contacts independently and manually mirror Clinical KB tokens/components. **Benefits:** Strongest operational and deployment isolation. @@ -305,7 +305,7 @@ Today keeps the approved action-first order on every viewport: `Referrals to rev | `/caring-contacts/guidance` | Programme boundaries and contextual help | readable wide/rail | | `/caring-contacts/reports` | Privacy-conscious aggregate operations | stacked/wide | -The `More` control opens a navigation sheet on compact layouts and exposes direct links on wide layouts. Patient search is scoped to the pilot team's received referrals and retained Callback episodes. It never queries the hospital-wide directory directly and never writes to browser search history or the Clinical KB search store. +The `More` control opens a navigation sheet on compact layouts and exposes direct links on wide layouts. Patient search is scoped to the pilot team's received referrals and retained Caring Contacts episodes. It never queries the hospital-wide directory directly and never writes to browser search history or the Clinical KB search store. ### 5.3 Overlay and full-screen decision inventory @@ -343,7 +343,7 @@ Use `Sheet`/`ConfirmDialog`; on phone, promote clinical decisions to a bottom sh 1. The hospital referral workflow sends a structured referral containing the approved minimum identity, discharge, mobile-source and agreement fields. 2. Today lists the referral under `Referrals to review`, ordered by first eligible contact-window timing without risk ranking. 3. An authorised aftercare clinician chooses `Accept`, `Return for clarification` or `Decline` with a structured reason. The latter two outcomes write back to the source workflow. -4. Until acceptance, the referring team remains responsible and Callback displays `Awaiting handover`; it never shows an aftercare owner. +4. Until acceptance, the referring team remains responsible and Caring Contacts displays `Awaiting handover`; it never shows an aftercare owner. 5. Acceptance moves the referral to the team queue. A coordinator explicitly claims it or a team lead assigns it before activation. 6. Search and selection reveal only the minimum identifiers needed to distinguish this team's referrals and episodes. 7. A deliberate identity-confirmation step repeats the selected referral, source identifiers, patient-controlled-mobile flag and imported agreement status. @@ -389,7 +389,7 @@ Use `Sheet`/`ConfirmDialog`; on phone, promote clinical decisions to a bottom sh - A later discharge after readmission requires a new linked referral and never automatically resumes or rebases the earlier episode. - A contact already claimed by the dispatcher shows `Processing — too late to change` and cannot be silently cancelled. - Contact-detail changes pause future sends until updated source-system mobile, patient-controlled - and discreet-SMS-suitability evidence is imported and reviewed; no test SMS, read-back or Callback + and discreet-SMS-suitability evidence is imported and reviewed; no test SMS, read-back or Caring Contacts attestation is added. - A retired template never silently edits activated message snapshots. Governance defines whether affected future contacts continue, pause for review or require a replacement pathway. @@ -486,7 +486,7 @@ Every read and mutation is team-scoped and deny-by-default. Service-role access ### 8.4 Record of truth -Callback is not the clinical record. The design requires structured milestone write-back while detailed transport and access evidence remains in Callback. Before pilot, the service must approve: +Caring Contacts is not the clinical record. The design requires structured milestone write-back while detailed transport and access evidence remains in Caring Contacts. Before pilot, the service must approve: - which system is authoritative for patient identity and mobile details; - where agreement, activation, pause, withdrawal, exception resolution and plan completion are recorded clinically; @@ -861,7 +861,7 @@ Follow this exact order so the shell and product signature stabilise before edge - Create: `src/lib/caring-contacts/sms-provider.ts`. - Create: `src/lib/caring-contacts/fake-sms-provider.ts`. -- Create: `callback-worker/index.ts`, `callback-worker/run-loop.ts`, `callback-worker/dispatcher.ts` and `callback-worker/types.ts` as a separate responsibility from the ingestion worker. +- Create: `caring-contact-worker/index.ts`, `caring-contact-worker/run-loop.ts`, `caring-contact-worker/dispatcher.ts` and `caring-contact-worker/types.ts` as a separate responsibility from the ingestion worker. - Create: `src/app/api/webhooks/caring-contacts/delivery/route.ts` with provider-neutral contract tests. - Add package scripts and worker/API tests through repository wrappers. @@ -888,7 +888,7 @@ Follow this exact order so the shell and product signature stabilise before edge - [ ] Implement the adapter behind the provider-neutral interface without changing domain logic. - [ ] Verify webhook signatures, replay prevention, status mapping and redacted observability. - [ ] Run canaries only with approved synthetic/test numbers and an explicit send budget. -- [ ] Prove the selected sender cannot receive replies and that no inbound payload, route, log or user interface exists in Callback. +- [ ] Prove the selected sender cannot receive replies and that no inbound payload, route, log or user interface exists in Caring Contacts. - [ ] Test webhook-primary status handling plus manual reconciliation after simulated outage, discrepancy and suspected incident; prove uncertain contacts are never resent automatically. - [ ] Complete `npm run check:production-readiness`, local release checks and the clinical-governance PR preflight. - [ ] Record hosted evidence separately from local evidence. @@ -906,8 +906,8 @@ Follow this exact order so the shell and product signature stabilise before edge - [ ] Perform accessibility acceptance with clinicians using ward desktops and supported phones, including physical iPhone Safari/PWA boundaries where applicable. - [ ] Open enrolment to every objectively eligible referral from the one pilot team; monitor queue age and workload continuously because there is no numeric patient cap. - [ ] Monitor duplicate sends, schedule drift, delivery exceptions, unresolved exceptions, withdrawals processed, access anomalies and privacy/security incidents. -- [ ] Run the separately consented patient-acceptability evaluation outside Callback and review aggregate lived-experience findings on tone, timing, sender identity and the one-way boundary. -- [ ] Run two weeks of seven-day hypercare with named clinical, service, technical, privacy and incident leads plus daily Callback queue/state review; provider-side reconciliation remains event-triggered. +- [ ] Run the separately consented patient-acceptability evaluation outside Caring Contacts and review aggregate lived-experience findings on tone, timing, sender identity and the one-way boundary. +- [ ] Run two weeks of seven-day hypercare with named clinical, service, technical, privacy and incident leads plus daily Caring Contacts queue/state review; provider-side reconciliation remains event-triggered. - [ ] Trigger an immediate service-wide pause for any confirmed wrong-recipient send, duplicate send, unauthorised content, material privacy/security incident or loss of audit integrity. - [ ] Permit restart only after joint incident-lead, privacy/security and clinical-programme approval. - [ ] Hold the first governance review at 6–8 weeks; permit only a controlled extension, then require longer-term pathway evidence before broad rollout. diff --git a/docs/superpowers/specs/2026-08-15-caring-contact-coordination-design.md b/docs/superpowers/specs/2026-08-15-caring-contact-coordination-design.md index 7da1e2b41..4c08cfaca 100644 --- a/docs/superpowers/specs/2026-08-15-caring-contact-coordination-design.md +++ b/docs/superpowers/specs/2026-08-15-caring-contact-coordination-design.md @@ -12,7 +12,7 @@ use clearly fictional synthetic identities and details; real patient information appear in them. All other fixtures, messages, people, services, identifiers and phone numbers are fictional too. -Callback is a dedicated operational workspace inside this repository. It inherits the Clinical KB +Caring Contacts is a dedicated operational workspace inside this repository. It inherits the Clinical KB v2 visual and accessibility contracts but is not a search mode. Patient or referral information must not enter shared search, RAG, OpenAI, favourites, recent-search, query-log or analytics paths. @@ -43,7 +43,7 @@ Reporting never moves above actionable work. `Needs action` is not an inferred-r ## 3. Referral, identity and episode boundaries The hospital workflow supplies minimum identity, discharge, mobile provenance, an explicit -patient-controlled/suitable-for-discreet-SMS flag and `Agreement confirmed: Yes/No`. Callback does +patient-controlled/suitable-for-discreet-SMS flag and `Agreement confirmed: Yes/No`. Caring Contacts does not represent the imported mobile as independently re-verified or the agreement as legal/treatment consent. @@ -52,7 +52,7 @@ reason. Before acceptance, the UI shows `Awaiting handover` and the referring te Acceptance moves the referral into the aftercare queue; a coordinator then explicitly claims it or a team lead assigns it. There is no automatic round robin. -Patient search is limited to the active pilot team's referrals and Callback episodes. Results are +Patient search is limited to the active pilot team's referrals and Caring Contacts episodes. Results are identity-forward rows followed by a separate assurance step. The chosen identity remains visible in flow through activation; `Change patient` requires object-specific confirmation. Team switching clears patient state before the new context renders. @@ -128,7 +128,7 @@ phone bottom sheets; inspection is a wide right drawer and phone full-height she withdrawal, activation and conflicts become full-screen phone stages. Every overlay is named, focus-safe, scrollable and leaves validation, focus and safe-area navigation uncovered. The frozen per-item 24-row modality and dismissal matrix in -`docs/caring-contacts/design-handoff.md` is binding; a generic one-modality Sheet path is not an +`docs/caring-contacts/interaction-matrix.md` is binding; a generic one-modality Sheet path is not an acceptable implementation substitute. ## 7. Content, visual and responsive contract @@ -177,7 +177,8 @@ design handoff: - [content style guide](../../caring-contacts/content-style-guide.md); - [clinical-language review](../../caring-contacts/clinical-language-review.md); - [accessibility and responsive acceptance](../../caring-contacts/accessibility-acceptance.md); and -- [developer handoff](../../caring-contacts/design-handoff.md). +- [interaction matrix](../../caring-contacts/interaction-matrix.md) — the binding 24-row modality and dismissal decisions. +- [linked prototype handoff](../../caring-contacts/linked-prototype-handoff.md). The local evidence is synthetic Chromium/source evidence only. Physical iPhone Safari and installed- PWA acceptance are unrun and required later. None of these documents converts the prototype into a diff --git a/docs/superpowers/specs/2026-08-19-caring-contact-production-build-design.md b/docs/superpowers/specs/2026-08-19-caring-contact-production-build-design.md index 5ce32c340..5acc85a87 100644 --- a/docs/superpowers/specs/2026-08-19-caring-contact-production-build-design.md +++ b/docs/superpowers/specs/2026-08-19-caring-contact-production-build-design.md @@ -31,18 +31,18 @@ will not need rebuilding. That is what this document specifies. ## 2. Decision-lock revisions — 19 August 2026 -The Approved decision lock of 15 August 2026 remains binding except for the following nine revisions. +The Approved decision lock of 15 August 2026 remains binding except for the following ten revisions. Each records its reasoning so a later reviewer re-opens it deliberately rather than by accident. ### 2.1 Replies receive an automated non-monitored response -**Was:** "Use a non-receiving sender. Callback receives, stores, analyses and displays no replies." +**Was:** "Use a non-receiving sender. Caring Contacts receives, stores, analyses and displays no replies." **Now:** patient-visible messages originate from a **receiving-capable dedicated number**. Any inbound message triggers an immediate automated response naming the programme line and its hours, one approved crisis-support contact, and emergency direction. Inbound content is **discarded at the provider boundary -and never persisted, transmitted to Callback, displayed, logged, counted per patient, or analysed**. -Callback still has no inbox, no thread, no reply workflow, and no per-patient reply signal. +and never persisted, transmitted to Caring Contacts, displayed, logged, counted per patient, or analysed**. +Caring Contacts still has no inbox, no thread, no reply workflow, and no per-patient reply signal. **Reasoning:** a non-receiving sender leaves a distressed patient who replies with either a carrier error or complete silence, immediately after a message from a mental-health team. Silence is the worst @@ -162,6 +162,25 @@ timestamp and purpose. No other export, download, or bulk extract exists. require a filed document, and an unscoped later exception is more dangerous than a bounded one written now. The prohibition otherwise stands. +### 2.10 The service is renamed from `Callback` to Caring Contacts + +**Was:** the workspace was named `Callback` throughout the rollout plan, the coordination spec and the +prototype shell header. No document recorded a reason for the choice. + +**Now:** the service is named **Caring Contacts**, matching the intervention's established name and the +repository's existing `caring-contacts` module naming. The proposed `callback-worker/` directory becomes +`caring-contact-worker/`. + +**Reasoning:** `Callback` names a promise the service explicitly does not keep. It never calls back, never +receives a reply and never responds. A patient told they had been enrolled in `Callback` could reasonably +expect a telephone call, which is the same expectation-mismatch hazard as the silent-reply problem +corrected in §2.1. A name should not have to be explained away in the first line of a patient-facing +script. + +**Consequences:** 41 occurrences renamed across the rollout plan, the coordination spec, this document and +the prototype shell header. No test asserted the old name. Any external material already carrying +`Callback` needs updating. + ## 3. Architecture ### 3.1 The sealed domain layer @@ -230,7 +249,7 @@ schema runs against a local Postgres instance so development is never blocked. All domain functions take an injected clock; no domain module reads ambient time. Sign-in is a **non-production role switcher** (coordinator, team lead, auditor) rather than real credentials: the -decision lock requires WA Health enterprise sign-on and states that no Callback-local credentials exist, +decision lock requires WA Health enterprise sign-on and states that no Caring Contacts-local credentials exist, so building a login would violate it, and the permission and auditor surfaces cannot be demonstrated without role switching. @@ -251,7 +270,7 @@ Each is demanded by a rule already in the decision lock and currently has no sur | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Service safety stop** | A confirmed wrong-recipient message, duplicate send, unauthorised content, material privacy/security incident or loss of audit integrity immediately pauses the entire pilot | Service-wide halt of all sending across every patient and team, with a categorised reason and acting person. Restart requires recorded joint approval from the incident lead, privacy/security owner and clinical programme lead; the interface must not permit single-person restart. A service-state banner is visible everywhere while active. | | **Pathway authoring and dual approval** | A clinical programme lead and a lived-experience representative both approve new or materially changed pathway/message versions | Draft, review, dual approval with named approvers and timestamps, publication, retirement, immutable version snapshots. Active plans keep their snapshot; an urgent safety retirement pauses affected future contacts for explicit review. | -| **Provider reconciliation** | Staff perform manual provider reconciliation when an outage, discrepancy or suspected incident occurs | Callback's expected dispatch record beside reported provider status for a bounded window; explicit resolution of each discrepancy; never automatically resends an uncertain contact. | +| **Provider reconciliation** | Staff perform manual provider reconciliation when an outage, discrepancy or suspected incident occurs | Caring Contacts's expected dispatch record beside reported provider status for a bounded window; explicit resolution of each discrepancy; never automatically resends an uncertain contact. | | **Auditor access trail** | Clinicians see episode-relevant history; privacy/security auditors see the complete access trail | Role-gated, read-only, filterable view of every search, view, decision, mutation, write-back and administrative access. | | **Workload and queue monitor** | The pilot has no numeric cap, so workload monitoring and stopping rules are mandatory | Queue age, unclaimed work against the 60-minute escalation, active plans per coordinator, exception backlog age. Operational only; never ranks clinicians. | | **Notification preferences** | Alerts contain no patient identifiers and require authentication | Per-user opt-in by alert class, with a preview demonstrating the identifier-free alert body. | @@ -427,22 +446,37 @@ done, and committed separately so any single piece can be reverted while the pul ## 14. Open register — recorded, not solved -None blocks this build; all block a real-patient pilot. - -| Item | Owner | Note | -| ------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Aboriginal health and cultural safety review | Aboriginal health governance | Required before any real patient; a culturally appropriate pathway is separate approved work. | -| Hosting: Railway has no Australian region | Josh, then a sponsoring service | The app tier runs in Singapore; the decision lock requires Australian residency for data, backups, logs and provider processing. A real-patient deployment needs a separately contracted Australian PHI-capable environment. | -| Provisioning the dedicated caring-contact Supabase project | Josh | Creating the project, its plan and cost, and the first hosted migration each need confirmation at the time. Sydney region. Synthetic data only. Development proceeds against local Postgres until it exists. | -| A shareable hosted demo instance | Josh | The dedicated Supabase project makes the data shareable; serving the application to someone else is a further decision, since the app tier would still run outside Australia. Acceptable for synthetic data, not for real patients. | -| Staff supervision and vicarious distress | Clinical programme lead | Coordinators carry a caseload of recent suicidal crises; no supervision model exists. | -| Wrong-recipient contact runbook | Service | What happens when an unconnected person receives a message and rings the programme line. | -| Death during the programme: notification and team support | Clinical programme lead | Cancellation is mechanical; who is told, and what support the coordinator receives, is unspecified. | -| Equity limitation: people without a patient-controlled mobile | Josh, for the governance submission | Eligibility systematically excludes some of the most marginalised patients. State it rather than be asked. | -| Provider inbound auto-response privacy position (§2.1) | Privacy review | Inbound content transits the provider even though it is never retained. | -| Retention figure | Records officer | Seven years is a working assumption only. | -| Sponsor case, costing and demonstration | Josh | No artefact yet addresses a clinical director rather than an engineer. | -| Physical iPhone Safari and installed-PWA acceptance | Josh | Chromium evidence cannot close it. | +None blocks this build; all block a real-patient pilot. Severity, controls and status for the clinical +items live in the [hazard log](../../caring-contacts/hazard-log.md). + +| Item | Owner | Note | +| ------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Named clinical safety officer | Josh, then the sponsoring service | Nobody owns clinical risk for the service. Hazard **H-00**. | +| Lived-experience review of the message set | Josh | Never done. The [message review pack](../../caring-contacts/message-review-pack.md) is ready to run. Hazard **H-04**. | +| Patient-visible reply wording is now inaccurate | Josh, then dual approval | §2.1 makes "Replies are not received, stored, analysed or monitored" untrue. The constant must change before any demonstration. | +| Aboriginal health and cultural safety review | Aboriginal health governance | Required before any real patient; a culturally appropriate pathway is separate approved work. Hazard **H-05**. | +| Hospital referral feed feasibility | Josh | Unconfirmed, and the largest programme risk. Questions, fallback and who to ask in [referral feasibility](../../caring-contacts/referral-feasibility.md). Hazard **H-44**. | +| Hosting: Railway has no Australian region | Josh, then a sponsoring service | The app tier runs in Singapore; the decision lock requires Australian residency for data, backups, logs and provider processing. A real-patient deployment needs a separately contracted Australian PHI-capable environment. Hazard **H-36**. | +| Provisioning the dedicated caring-contact Supabase project | Josh | Creating the project, its plan and cost, and the first hosted migration each need confirmation at the time. Sydney region. Synthetic data only. Development proceeds against local Postgres until it exists. | +| A shareable hosted demo instance | Josh | The dedicated database makes the data shareable; serving the application to someone else is a further decision, since the app tier would still run outside Australia. Acceptable for synthetic data, not for real patients. | +| Staff supervision and vicarious distress | Clinical programme lead | Coordinators carry a caseload of recent suicidal crises; no supervision model exists. Hazard **H-43**. | +| Wrong-recipient contact runbook | Service | What happens when an unconnected person receives a message and rings the programme line. Hazard **H-13**. | +| Death during the programme: notification and team support | Clinical programme lead | Cancellation is mechanical; who is told, and what support the coordinator receives, is unspecified. Hazard **H-14**. | +| Equity limitation: people without a patient-controlled mobile | Josh, for the governance submission | Eligibility systematically excludes some of the most marginalised patients. State it rather than be asked. Hazard **H-15**. | +| Provider inbound auto-response privacy position (§2.1) | Privacy review | Inbound content transits the provider even though it is never retained. Hazard **H-35**. | +| Retention figure | Records officer | Seven years is a working assumption only. Hazard **H-34**. | +| Sponsor case and costing | Josh | Partly addressed by the [evidence brief](../../caring-contacts/evidence-brief.md), whose citations are unverified, and the [demonstration script](../../caring-contacts/demo-script.md). Costing is still absent. | +| Physical iPhone Safari and installed-PWA acceptance | Josh | Chromium evidence cannot close it. | + +## 14a. Companion documents + +| Document | Purpose | +| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| [hazard log](../../caring-contacts/hazard-log.md) | Every clinical, privacy and operational hazard with severity, controls, status and owner. | +| [evidence brief](../../caring-contacts/evidence-brief.md) | The honest evidence position for a sponsor, including the null trials. **Citations unverified.** | +| [referral feasibility](../../caring-contacts/referral-feasibility.md) | Questions to ask about the hospital referral feed, who to ask, and the manual fallback. | +| [message review pack](../../caring-contacts/message-review-pack.md) | How to run the lived-experience review, and the reply-wording correction it must settle. | +| [demonstration script](../../caring-contacts/demo-script.md) | The five-minute path through the built system. | ## 15. Approval boundary diff --git a/src/components/caring-contacts/mockups/caring-contact-shell-frame.tsx b/src/components/caring-contacts/mockups/caring-contact-shell-frame.tsx index b386a9c11..948ed4c54 100644 --- a/src/components/caring-contacts/mockups/caring-contact-shell-frame.tsx +++ b/src/components/caring-contacts/mockups/caring-contact-shell-frame.tsx @@ -131,7 +131,9 @@ export function CaringContactShellFrame({