How each module gets a third setting, drafts: Clara prepares the replies and actions, and a person at the customer approves them before anything goes out.
2026-09-29 · design only, no code · board rows gk-drafts-mode (11) and gk-settings-page (12) · decision b90675488 · extends ADR-0139
Drafts is how renewals already work. Since #13009, when a company has renewal review on, a renewal reply is held instead of sent. It waits in the same queue, Slack post and review page as held emails. Drafts mode turns that into a setting per module and per building, replacing two separate company switches.
In drafts, Clara does the work and someone on the customer's team presses send. Renewals already works this way, so most of this is extending code we already have.
The boolean stays the only on/off answer. A mode goes next to it.
Organization.settings.enabledModules[m] stays true|false. A new field, moduleModes[m] = 'drafts', sits on the same record, so one read returns both and there is no second read to fail.<module>.module row becomes {enabled: true, mode: 'drafts'}. A building row always stores its full state, and a row without mode means live. The 73 rows from the capabilityStage move are all {enabled:false}, and any {enabled:true} row the back-office card wrote keeps reading as live, so no existing row changes meaning.resolveModuleState() → off | drafts | live | unresolved, is added next to resolveModuleEntitlement rather than replacing it. The building's value wins, then the company's. unresolved is its own value, and callers treat it the way they do today.buildingModuleSettingOf rebuilds only {enabled}, and foldBuildingModule seeds the company rung with {enabled} only. Both have to pass mode through, and each needs a test.| Stored today | Reads as | Migration |
|---|---|---|
true, or absent everywhere | live | none |
false (company or building) | off | none, because mode is ignored when the module is off |
reviewRenewalMessages = true | renewals in drafts | one-time script with read-back; after that, the old switch reads from the new setting |
reviewOutboundEmails = true | prospects in drafts, for Clara's prospect emails only (Q6) | same script. This switch also holds team-facing escalation emails (decision requests, nags, collections owner alerts), which belong to no module, so it stays in place for those |
The fold may only add holds, never remove one. Each old switch keeps working until the new setting has been read back, so no customer gets more live sends because of the migration.
OFF refusals keep working without edits. Every gate refuses only on <module>_module_off, and drafts counts as a kind of ON. New code goes only where a prepared item can be held.
When the setting changes: going from drafts to off means pending drafts for that module are refused if someone approves them, and they are marked expired. Going from drafts to live leaves pending drafts waiting for approval rather than sending them automatically, because ADR-0139 §7 says turning a module on never replays old work. Going from live to drafts only affects work that starts after the change.
If the setting cannot be read, a drafts building sends as if it were live, as it would today, because we cannot tell it was in drafts. Q4 asks whether that is acceptable.
Every layer asks the same read. As in ADR-0139, no layer assumes an earlier one already held the item.
| Layer | In drafts | On approve | On reject |
|---|---|---|---|
| Clara's replies (text, email) | Held. The #13009 hook (withClaraReplyRowDeferred and holdIf) holds back the reply's row. classifyReplyTopic, which already returns maintenance, picks the module. The reply goes to the held-message queue (EscalationHold, new source clara_reply_sms or _email). | Checks the setting again, and if the module is now off, refuses. Otherwise it sends the stored words through the send door with the real module and an approval id. The conversation row is written when the message sends, and the same draft cannot send twice (as in approveHeldText). | Nothing is sent. A note goes on the conversation and the team takes over the thread. |
| Tool actions and AppFolio writes | The tool gate prepares the action and does not run it. It is stored on that turn's draft, using the lifecycle of the renewal and new-lease change reviews: pending, then executed or execution_failed. | A turn's reply and its actions are approved together. The actions run first, and the reply sends only after they succeed. If one fails, the reply stays pending and the approver sees the failure, so the resident is never told something was done when it wasn't. Before anything runs, the setting and the live AppFolio state are checked again. Writes go through the per-building work-order writer, the same place OFF refusals happen. | Discarded, with nothing written to AppFolio. |
| Automation (auto-start, chases, reminders) | Workflows still start, since starting one sends nothing. Any step that reaches a person is held, the way renewal outreach texts are today (held-text.ts). If a newer draft arrives on the same thread, it replaces the older pending one. | Sends that step. | Skips that step, and the workflow continues as it would after any refused step. |
| Promises | A promise in a held reply is not recorded yet. | Recorded, with its follow-ups and pages. | Voided, so nobody is paged about a promise the resident never heard. |
| Send door (backstop) | A send in a drafts module with no approval id is refused and recorded, as OFF sends are today (recordModuleRefusal). The door has no thread context, so it cannot make a reviewable draft. A refusal here means an upstream lane missed its hold, so it raises an alarm, not a quiet log line. | A drafts send goes out only when it has an approval id and the setting does not read off. | |
| Always live | emergency, team_alert, login_code and staff_reply are never held. The hold check reads the front door's reason first, so a life-safety turn (already mapped to emergency) never reaches the topic check. Also, the notice telling the team a draft is waiting is itself a team_alert. | ||
/admin/escalation-holds), in its Slack post, and in a Drafts tab on /review built on the shared ApprovalPanel (row 12). "Needs you" is an internal agent page, not something customers see. /review is where customers see what needs their attention.isActiveOrgOrPlatformAdmin) and change reviews need conversations:edit. The proposal is anyone who can edit that module at that building (Q2).staff_reply, and there is no new always-on kind. The words are still Clara's and belong to a module, so the send declares that module and is refused if the module has since been switched off. This matches ADR-0139 §2, where OFF also refuses staff "send now".This builds on the settings audit's Q2 and Q5. Q2 says the company sets the default, a building can override it, and a badge shows where the value comes from. Q5 says turning a setting down can only make Clara do less.
BuildingModulesCard (inherit / on / off), with on split into drafts and live.Each part branches off origin/main. Parts 11.1 to 11.3 can be open at the same time.
| Part | What ships |
|---|---|
| 11.1 | Maintenance texts in drafts, end to end, dark. Adds mode to both stored shapes and adds resolveModuleState. Widens the #13009 hook from "the renewal review switch is on" to "this reply's module is in drafts here". Maintenance replies are held as clara_reply_sms and approved through the existing hold route, which reads the module from the hold row. The only way to set drafts is the existing building-module script. Includes the ADR-0139 amendment. |
| 11.2 | Maintenance actions. In drafts, write tools prepare instead of running, and the prepared action is attached to the turn's hold. On approve it runs through the per-building work-order writer after a fresh check. The held reply must not say the action already happened. |
| 11.3 | The send-door backstop, plus maintenance automation (vendor chases, reminders, rating prompts). A newer draft replaces an older one, and promises are recorded only on approve. |
| 11.4 | Maintenance email replies, using the held-email path that already exists, and calls, depending on the answer to Q7. |
| 11.5 | Fold reviewRenewalMessages and reviewOutboundEmails into drafts. prod data, needs a go |
| 11.6+ | One PR per module: prospects, renewals, collections. Collections dunning letters already always need approval (ADR-0125). |
| 12.1 | Back office: BuildingModulesCard and the company module picker get a Drafts option, and the route accepts it. |
| 12.2 | Customer settings page: the Modules card and the buildings table from section 3. |
| 12.3 | A Drafts tab on /review, approval by customer roles, and editing before approving (depending on Q8). |
Q3 and Q5 were answered by Gera in chat. The rest were settled from existing rules by the decider; its receipts are listed in brackets.
drafts. The setting reads Off · Supervised · Live, and every module gets it (Maintenance, Leasing, Renewals, Collections), each module turned on for it once its hold works end to end. Where this page says Drafts, read Supervised.docs/adr/0139-gatekeeper-one-module-switch-per-customer.md; src/lib/domain/modules/{resolve-module-entitlement,building-module-chain,refuse-if-module-switched-off,always-on,write-building-module}.tssrc/lib/integrations/twilio/client.ts (module gate, moduleUnresolvedPosture, recordModuleRefusal); text-send-module-fence.test.tsagents/clara/lib/messaging/{reply-module,process-envelope}.ts; renewal-orchestration/{renewal-reply-review,classify-reply-topic}.tsdata/dynamo/escalation-hold.ts, escalation/{held-text,bake-gate}.ts, renewal and new-lease change reviews, collections dun review, tenant-confirmation/review-rows.tsmaintenance/module-disclosure-rules.ts (DISCLOSURE_RULES covers OFF, not drafts); Gatekeeper page; settings decisions Q2, Q3, Q5