Gatekeeper rollout plan

Let 5–10% of Supervised conversations go out on their own, ramp it up on a schedule, and give temporary gates a review-by date. A plan for Gera to approve. Nothing is built yet.

2026-10-22 · plan only, no code · builds on ADR-0144 and #21757

The idea

A Supervised module gets a ramp: 0% means everything is held, as it is today. 10% means one conversation in ten goes out without waiting, and the same thread always gets the same answer. 100% means everything goes out, and then a system admin switches it to Live with one click.

The ramp moves up by date. Rejecting a held message pauses it. Supervised and test gates can carry a "review by" date. When that date passes, nothing happens and no alert goes out. Claude can list the overdue ones when asked.

Three PRs, each under 300 lines

One fixed %: Clara's text and email replies are released at a stored % for one module at one company. Released replies are labeled on /review.
The schedule: steps by date, a rejection pauses the ramp, and the plan is shown and edited on the customer page.
Review-by dates: a "which gates are overdue?" command and a filter on the admin customer list.

Your call

Approve this plan?

Approve, build it Change first (note below)

Two open questions are in the last fold, each with a recommendation.

1 · How the ramp works

Where it applies. It only applies when the module is Supervised at that building. When the module is Off or Live, the plan is ignored. It is a setting that hangs under its module, not a second status (ADR-0144 §4a).
The stable pick. We turn the conversation, the module and the plan's start date into a number from 0 to 99. The reply is released if that number is below today's %. The same thread always gets the same answer. As the % goes up, a thread that was already released stays released. A new plan has a new start date, so it picks a fresh set of conversations.
The schedule. The plan is a list of steps, for example 10% from Oct 24 · 20% from Oct 31 · 50% from Nov 7 · 100% from Nov 14. Today's % is worked out at the moment a message is decided, from today's date and the steps. There is no cron and no sweeper, so nothing has to wake up to move the ramp.
"After N clean days." When a reviewer rejects a held message for that module, the plan records the date. A step only starts once its date has come and N days have passed since the last rejection. So a rejection pauses the ramp at its current %. It never pushes the % up.
At 100%. Everything is released. The overdue command and the admin filter list the module as "ready for Live". A system admin flips it with one click, and that ends the plan. The system never changes a module's status by itself.

What a released message looks like

Both send doors, for texts (twilio/client.ts) and for emails (company-live-gate.ts), refuse an unapproved Clara message at a Supervised building, and they page someone when they do. A released reply that reached a door without an approval would be lost, not sent. To avoid that, a released reply is held exactly as it is today. The hold row is then marked at once as released by the rollout (10%), and its id is passed to the door as the approval. The doors don't change, every release leaves a record, and /review can show and filter it ("Released automatically · 10%"). That's what lets reviewers spot-check what went out.

What it covers, and what it doesn't

Covered from part 1 Not covered (stays fully held)

Clara's text and email replies, in every module, that go through her conversation loop. Those all pass one rule, decideSupervisedReplyHold, so one check there covers them. Two maintenance replies that skip the loop: the router's quick acknowledgements (the first-rating and first-answer replies, held after the loop) and replies to the in-house handyman. They are held at their own sites, and they join in part 2.
Outreach Clara starts herself (renewal offers, past-due reminders, prospect follow-ups), owner reports and team notices. Each can join later, one lane per PR.
Property-software writes (held turnover and new-lease writes, HeldPmsWrite): always held, whatever the plan says. A wrong charge in AppFolio costs more than a slow reply.

Covered from part 1	Not covered (stays fully held)
Clara's text and email replies, in every module, that go through her conversation loop. Those all pass one rule, `decideSupervisedReplyHold`, so one check there covers them.	Two maintenance replies that skip the loop: the router's quick acknowledgements (the first-rating and first-answer replies, held after the loop) and replies to the in-house handyman. They are held at their own sites, and they join in part 2. Outreach Clara starts herself (renewal offers, past-due reminders, prospect follow-ups), owner reports and team notices. Each can join later, one lane per PR. Property-software writes (held turnover and new-lease writes, `HeldPmsWrite`): always held, whatever the plan says. A wrong charge in AppFolio costs more than a slow reply.

Urgent repairs skip the hold today (skipsSupervisedHold), and that stays as it is.

2 · Review-by dates (expiry)

Only on temporary gates: a Supervised module, which gets its date on its plan, and gates of kind test/safety. In the inventory there are 60 test/safety gates and 16 module gates, out of 372. A plain on/off feature can't have one. A drift test refuses a review-by date on any other kind.
Where the date lives. For a company or building Supervised module, it goes in the same plan row as the ramp. For a gate declared in code (test and platform gates), it is a reviewBy field on its registry entry, set in the PR that adds the gate. Most test gates are still hosting settings that aren't in the registry yet. Until they are, their date goes on their row in the switch inventory, and the command reads it from there. Claude picks the date, and it doesn't have to be exact.
When the date passes, nothing happens. No alert, no Slack post, and no change in behaviour.
Asking. A read-only command, npx tsx scripts/gatekeeper/gates-due.ts, prints every gate past its review date, plus every ramp at 100% that is "ready for Live". It shows the company, the building, the gate, the date and who set it. The same list is a filter on /admin/customers ("Review date passed"). The command never writes anything.

3 · Who sets it

A system admin, meaning Gera, Fede or Sean. This uses the check #21757 just made standard: requirePlatformAdministrator, which reads the staff platform-admin roster. The plan is written through a route under /api/admin/companies/[id]/…. admin-scope-inventory.drift.test.ts already fails CI on any route there that skips that check, so no new permission code is needed.

The usual flow: you tell Claude "start Maintenance at Situs at 10%, then 20% next week". Claude proposes the steps and a review-by date, and the plan is saved through the admin page under your name. Starting a ramp at a real company turns sending on for part of its conversations, so it needs a system admin's word each time. Once a plan is saved, the steps move on their own, because the plan was the approval.

4 · Data model, the smallest change

Add one new registry key, with one slot per module: gate.plan.maintenance, gate.plan.leasing.prospects and so on. This follows the existing slot pattern (vendor_roster.plumbing). It is a PARAMETER key, writable at the company and building levels. An absent row means "no plan", which is today's behaviour. The value is:

{ steps: [{ percent, from }], cleanDays?, lastRejectAt?, reviewBy?, startedAt }

Precedence lives only in foldEffective. A building's own plan beats its company's. The reader uses the same fold as every other setting and never restates "building first, then company".
It is stored as a settings row (ATTACH#setting#). There is no new field on Organization or Property. The company's Supervised marker stays where it is (settings.moduleModes).
No data migration. No existing row changes.

ADR-0144 §7 asks for the registry row in the PR. Here it is:

Gate	scope	kind	owner	source	default	visible	description	decision
`gate.plan.<module>`	building	feature (under its module)	System admin	settings registry	no plan (everything held, as today)	yes (see Q2)	While the module is Supervised, a share of conversations goes out without waiting for a person.	(a)

5 · The three PRs

Part	What ships, end to end	Dark until
1	The registry key, with one fixed % only (one step). The pure pick and today's-% functions. The check inside `decideSupervisedReplyHold`. The "released by the rollout" hold state, with its id passed to the send doors. A /review label. The system-admin route, plus `gates-due --show` to read a plan back.	A system admin stores a plan. With no plan anywhere, behaviour is byte-identical to today.
2	Multiple steps, with clean days. The reject path records `lastRejectAt`. A "Rollout" select row under the module on `/admin/customers/[id]`, built on `FeatureSelectRow` the way "Handyman texts" is. A "Released automatically" filter on /review. The two maintenance reply sites that skip the loop (quick acknowledgements, handyman replies) go through the same check.	As in part 1.
3	`reviewBy` on the plan and on registry entries. The drift test that refuses it on plain features. `gates-due` lists overdue gates and "ready for Live" ones. The filter on the admin customer list.	Nothing to turn on; the command only reads.

Each part branches off origin/main, and up to three are open at once. Part 1's PR body carries the ADR-0144 §6 census, read from prod with the real readers. Because no plan row is stored anywhere, the expected result is that no building changes. It also carries the Dark: gate.plan | feature | proof | turn-on: system admin line.

6 · How we prove it

Pure tests on the pick. The same conversation always gets the same answer. Raising the % never un-releases a thread. Over 10,000 synthetic ids, the share released lands near the stored %. 0% means nothing is released and 100% means everything is.
Schedule tests. The right step on a given date. A rejection pauses the ramp. A step waits for its clean days.
Fold test. A building's plan beats its company's. A company plan reaches a building that has none of its own. A plan at a Live or Off building does nothing.
Door test, the one that matters. A released reply passes both send doors. An unreleased one is still refused, just as today. The test uses the real door code, not a hand-built mock.
Replay before turning it on (Art. III.4). A read-only pass over the last 30 days of real Supervised holds. It answers two things: what share would have gone out at 10%, and which of the messages a person rejected would have gone out. Each of those is listed in the PR, by hand, with a label.
Willows run. 50% on the test building, with registered phones only. We check that some threads send, some hold, and every released one shows on /review.

7 · Risks

A bad reply reaches a real person without review. This is the point of the feature, and also its cost. To limit it: start at 5–10%, cover replies only (never property-software writes), pause on any rejection, and label every release on /review so it can be spot-checked.
Fair housing. The fair-housing and promise checks (runOutboundSafetyChecks), and the hallucination guard, run inside Clara's loop on the finished draft. That happens before the Supervised hold is asked (both are in conversation-manager.ts; the safety checks come first, then the hold hook). So a released reply has passed every guard that a Live reply passes. The hold was never the fair-housing control. Part 1 adds a test that pins this order.
A released reply lost at the send door, if it reaches the door without its approval id. The door test above exists to catch this.
Quiet hours. A released reply follows the Live rules, so the overnight hold and the urgent carve-out stay as they are.
Two threads, one person. The pick is per conversation, as asked. Someone who texts and also emails could get one reply released and the other held. That is acceptable.
Forgotten ramps. Covered by the review-by dates and the overdue command, with no alerts, as you asked.

8 · Two open questions (with a recommendation each)

Q1. When someone rejects a held message, should the ramp pause at its current %, or drop back one step?

Pause (recommended: simple, and nothing goes backwards by surprise) Drop back one step

Q2. Should the customer's own team see the % on their settings page ("Supervised · 10% go out on their own"), or only our staff?

Customer sees it (recommended: they think Supervised means they approve everything) Staff only

Already decided on this page, not asked: property-software writes stay fully held, and 100% never switches a module to Live by itself.