The Purchase-Order Pivot — vendor coordination strategy, evidence & ADR-0116

This page is the whole story: what the evidence says about how Camellia actually coordinates vendors, how each PropFlow channel behaves today and where it breaks, what turnovers need, the decision (ADR-0116), and the phased plan. The full technical specification lives in the appendix at the bottom and in the canonical ADR (docs/adr/0116-vendor-facing-job-reference-per-property.md, merged in PR #4720).

1. The strategic problem, in one paragraph

Every vendor-facing thing PropFlow does — dispatch emails, outbound calls, SMS, reply attribution, turnover scheduling — is built on the assumption that the work order is the number vendors live by. At our only real production property, that assumption is false. jpco runs Camellia's vendors on AppFolio purchase orders: the PO is the number given at scheduling, the number vendors put on invoices, and the number they chase when it's missing. The work order is an internal artifact vendors never see — and worse, PropFlow is minting AppFolio work orders no human at jpco uses, then waiting on WO-status changes that structurally can never come. The pivot is not "add POs"; it is make the vendor-facing job reference a per-property fact instead of a hardcoded one, and re-anchor every channel — voice, email, SMS, attribution, turnovers — on that fact.

2. The evidence base

Everything on this page traces to one of these research assets (all produced from production data, 2026-07-27):

3. How the humans actually do it (the Joanna spec)

The workflow Clara has to slot into, as evidenced — not as imagined:

1. The PO is cut first, and it is what confirms the job — see the unit, put the PO in AppFolio, then call the vendor. What lags is transmission, not creation: "I'll have that PO, I'll reply with the PO if that's okay, or I'll call you back." PM-confirmed 2026-07-28 — see the callout below; this page previously read the quote as evidence the PO did not yet exist, which was wrong.
2. Erika creates the PO in AppFolio (351 of 381 modern POs) — the number comes from a strictly sequential shared counter. Approval (Kayla) is decoupled and late: median 15 days, and 4 of the 5 PO numbers spoken on real calls were still Pending when spoken.
3. Joanna reads the number to the vendor over the phone, off a list. The PO number moves by voice: across 35,315 PropFlow messages, a PO regex hits 3 times — all voice. In email it appears only as a hand-typed line in a reply (34 instances: "The PO is 662").
4. The vendor invoices against it — and chases when it never arrived (Miracle Method invoiced 9 days after the PO existed because nobody had transmitted it).

Why it matters for the design. Three consequences, all new as of this confirmation: (1) the 15-minute PO sync is comfortable by construction — a PO exists before the PM ever dials, so the read model never races a vendor callback; (2) outbound and inbound become asymmetric — a vendor calling about a job with no PO is normal, but an outbound-initiated job with no PO is off-process ("they need a po before we can do anything") and should be flagged, not worked around; (3) outbound scheduling calls should lead with the PO number, because it is what the vendor's back office keys on (17/21 sampled invoice PDFs carry it back, §7). Those become the outbound lane in §8.

Two structural facts still matter for design: the PO lags the turn (a unit routinely sits for days after move-out before any vendor work is scoped and a number cut — "no PO yet" is a normal state on a turn, not an error), and vendors have learned to route around Clara — "speak to Joanna" opens half of the PO calls in the golden set.

4. Channel by channel: today vs. what changes

The "after the pivot" column has shipped. Every row above is on main as of 2026-07-28 — the resolver and its five chokepoints in #4745, the inbound triage lane in #4760 — with one exception: the spend view (phase 4b) is unchanged. What has not happened is flipping Camellia's mode, so at Camellia these paths still resolve to work_order and behave exactly as the "today" column describes. Ship log: §8.

5. Turnovers: how they work today, and what must change

The turnover inspection produced the sharpest single finding of the whole effort. Today's turnover flow at a PMS property: PropFlow detects a departure → creates scope items → mints an AppFolio work order per work item → dispatches vendors referencing that WO → waits for the AppFolio WO status to change to mark the step complete (ADR-0030: AppFolio WO status is authoritative, polled every 60s).

At Camellia every link in that chain is broken:

• The minted WOs are theater. CAM-1259/CAM-1260 (paint + cleaning, unit 116) have sat open and untouched for a month — no human at jpco works out of AppFolio work orders.
• The completion signal can never arrive. jpco never closes AppFolio WOs (and never marks POs Received), so a workflow gated on WO-status change waits forever. That is why 24 of 25 Camellia turnovers are wedged (23 at notice_received, one at work_scheduled).
• The real coordination happens on POs we can't see or say. Metropolitan's "Clean House 7 days" / "Clean House 4 days" POs — negotiated on calls in the golden set — are whole-property work items our scope vocabulary literally cannot express, from a vendor whose trade (blinds is another — Camellia's 4th-biggest PO vendor) isn't in the trade vocabulary either.
• The turn↔PO relationship is loosening, not tightening: turn↔PO coverage fell 78% → 26% across the regimes, and the move-out→PO lag has blown out (chart below). "No PO issued yet" is the majority state of a modern Camellia turn — the design treats it as normal, never as an error or a blank screen.

What changes for turnovers:

1. Stop gating completion on AppFolio WO status at purchase_order properties. The signal must come from what actually happens: vendor reply ("job's done"), PM confirmation, or inspection — the completed work order is the industry's closest analogue to a service-entry sheet, and at Camellia we are the only party who can author it.
2. Make minting AppFolio WOs optional per property. Where no human uses them, they create confusion and a false integration surface. (WO minting keys off the same vendorJobReferenceMode decision — one config, coherent behavior.)
3. Extend the scope vocabulary: a blinds trade, and whole-property work items so "Clean House N days" is expressible and bindable (the PO model handles 1:0 property-wide POs via a sentinel).
4. Bind POs to turnover jobs so the turn board shows commitment reality: which steps have a PO, which are waiting (normal for ~2 weeks), what the committed cost is.

Un-wedging the 24 stuck turnovers is an ops action gated on the completion-signal redesign — they cannot self-heal under the current rule.

6. Vendor adoption: earning back the front door

Half of the PO calls in the golden set open with "speak to Joanna" — vendors have learned to route around Clara, because on their core business she has been a dead end (scripted refusal of the PO question, "I can only open work orders for current residents," transfer). Adoption is therefore a trust-repair problem, and the levers are ordered by what the evidence says actually retrains a caller:

1. Competence before persuasion. Nothing works until Clara can do the job: give the PO number, answer PO/billing status, know the vendor's open POs. That's phases 1–3 — adoption is the reason for the pivot, not a separate campaign.
2. Prove it in the first utterance. Company-name recognition (#4709) + listOpenPosForVendor means a recognized vendor gets context immediately — "Hi Mike — calling about the unit 210 fridge, PO 667?" — the capability is demonstrated before the caller can ask for Joanna. The strongest anti-routing move is the first five seconds.
3. Never fight the handoff — convert it. On "speak to Joanna": offer the concrete thing once ("I can give you the PO number or scheduling right now — or I'll get Joanna") and transfer gracefully if insisted. Then loop back with the artifact: after the human handles it, Clara sends the confirmation SMS/email carrying the PO — so even a routed-around call ends with Clara being the system that delivered the number they keep.
4. Outbound is the retraining channel. Every dispatch email and outbound call that carries the right number teaches vendors that Clara is where the numbers come from. Today the humans are the only source of POs; after phase 3, Clara is the fastest source — "reply to this thread or call this line and reference PO 682" makes her the path of least resistance.
5. Retire the trust-burning failure strings. The both-direction evals plus a dedicated eval on the golden set's 14 clara_failed calls: the exact utterances that taught vendors to skip her must score zero.
6. Measure it or it didn't happen. Baseline from the golden set (66 calls): handled by Clara 11, human-after-transfer 40, failed 14; "speak to Joanna" opens 4/8 PO calls. Standing metrics: transfer-request rate on vendor calls, Clara-resolved rate, per-vendor trend (a trust ledger per VendorCompany — A&K's trajectory matters more than the average). Reviewed against the baseline after Camellia flips.
7. Optional accelerator (needs Fede's sign-off on copy): a one-time note to the top PO vendors — "you can now get PO numbers and scheduling instantly at the Camellia line" — outbound customer-facing comms, so drafted only on request.

Prevention long-term: the routing-around behavior returns whenever Clara's competence lags the vendors' actual business. The adoption metric belongs on the same dashboard as the sync-health strip — a rising transfer-request rate is an early-warning signal, not a UX nit.

7. What the industry + the paper trail say

Doctrine (research-verified, honesty-labeled)

• WO = task authorization, PO = spend commitment. The boundary concept is encumbrance — "did this reserve money before it was spent?" A WO never answers that. Both WO-only and PO-first shops are coherent; jpco's PO-first Camellia is one of the two normal modes, not an anomaly.
• Vendor labor breaks the classic three-way match (no goods receipt) — the repair path is a two-way match (PO ↔ invoice). That's why unit turns are a PO-free zone in every PMS's docs, and why our completion signal has to come from confirmation, not receiving.
• In every PMS surveyed, the WO↔PO link is manual, optional, data-free — and unused. 0 of 722 linked at jpco is the expected outcome of that design, not negligence. The bill is where the two documents actually meet (AppFolio bills carry both fields). Design implication, verbatim from the doctrine doc: "the linkage is worth capturing, but not worth asking a human for" — infer it, confirm exceptions.
• Honesty flags survived two more research passes: the "operators hate double entry" pain point is attested in adjacent industries (EAM, ERP, auto repair) but still never in PM; the "8–15% spend reduction" figure is marketing — the defensible number (AER 2009) is ~7% on unit price for commodity spend moved onto contract.

The invoice-PDF finding (new, flips an earlier conclusion)

Sampling 44 invoice attachments from the mailbox: 17 of 21 PO fields inside the PDFs are populated with a real Camellia PO — including five vendors whose emails never mention one (MTech, Home Depot, HD Supply, Bomar, Metropolitan). Genuinely PO-free invoices: Anchor Pest (keys to our WO number — the one vendor that uses it), American Garage Door, TK Elevator, Western States. Miracle Method and A&K never email invoices at all. Caveat that shapes the design: ~12% of printed POs are wrong (HD Painting stamped a Metropolitan PO on its invoice) — invoice-extracted POs must validate against the PO read model, never be trusted raw.

8. The decision (ADR-0116) and the phased plan

The decision, in five lines (full text in PR #4720, merged):

1. The vendor-facing job reference is per-property configuration — Property.vendorJobReferenceMode: 'work_order' | 'purchase_order'; absent = today's behavior; set at onboarding with an advisory auto-suggestion; no third mode until observed.
2. One resolver, vendorFacingRef(), consumed by all five existing chokepoints; drift-guarded; returns "no reference yet" gracefully.
3. A read-only, PMS-agnostic PurchaseOrder read model (AppFolio proven; 15-min sync; 60-min discovery / 24-h render staleness budgets).
4. PropFlow owns the PO↔job binding — heuristic proposal (vendor+unit+date; 0.8% collision rate at a 7-day window), PM-confirmed before anything vendor-facing renders it; no auto-confirm in v1 (~1 card/workday).
5. PropFlow never writes or mints a PO. Ever. ADR-0030's principle extended; enforced by drift guards and both-direction evals (a WO property never emits a PO; a PO property never emits a WO number; no PO → never an invented one).

Shipped — the ship log as of 2026-07-28

Phases

The outbound lane — proposed, not decided

All three trace to the 2026-07-28 PM exchange in §3, and all three are Fede's call on review of #4773 — nothing here has been built.

9. Risks & open decisions

Data model

PurchaseOrder (derived read model — rebuildable by blind put, nothing PropFlow-authored beyond resolved* match-backs)
  PK PROP#<propertyId>  SK PO#<externalPurchaseOrderId>
  GSI1 VENDORPO#<vendorCompanyId>         → open POs per vendor (call prep)
  GSI2 PONUM#<orgId>#<purchaseOrderNumber> → org-scoped number lookup (returns ARRAY — ambiguity is the caller's problem)
  purchaseOrderNumber is a vendor-facing STRING: never parsed, keyed, or sorted; never minted.

PurchaseOrderJobBinding (canonical, PropFlow-authored)
  PK PROP#<propertyId>  SK POBIND#<poId>#<workOrderId | 'PROPERTY'>   GSI1 POBINDWO#<workOrderId>
  status proposed|confirmed|rejected|superseded · tier high|medium (low writes no row) · signals[] · bindingGroup
  Only CONFIRMED drives vendor-facing renders. Rejection sticky at unchanged hash; changed hash on confirmed → needsReconfirm (stays confirmed).

Sync & staleness

rate(15 min) lambda job · rolling 18-month window · contentHash diff (steady-state zero writes)
budgets: discovery 60 min (watermark-alerted, never silent) · vendor-facing render 24 h cache-only (past budget → suppress number, describe job)
       · reply attribution 24 h cache-only (miss → NO attribution, never a guess) · binder same-tick
failure posture: zero-row guard (never mass-remove) · vanished → removedInPms, never delete · 4 consecutive failures → alert

Binder scoring

candidates: wo.createdAt ∈ [po.createdAt − 45d, +7d]   (asymmetric — PO lags job)
score: vendor exact +50 / no-vendor +20 (different vendor → dropped) · unit +30 · date 0–15 peaked 13d
       · trade +15 · instructions token-match 0–15 · competing-PO −40
tiers: high ≥80 + margin ≥25 + unique → one-click confirm · medium 55–79 → top-3 picker · low → Unbound (manual)
floors pinned in po-binder-corpus.test.ts: high-tier precision ≥ 0.98, coverage ≥ 0.85
       measured on the hand-labeled Camellia book: precision 1.00 (4/4) · coverage 0.93 (14/15)

Guard rails

po-read-only.drift.test.ts — no PO write path exists, anywhere, ever
vendorFacingRef guard — no template reads purchaseOrderNumber directly
evals pinned both directions — work_order property never emits a PO; purchase_order property never emits a WO number;
                               no PO → "I don't have a PO number for that yet", never invented
Clara: PO arrives as call-start dynamic variable; NO new voice tool (mid-call lookup = the corpus's worst failure mode)

Prepared by Fable, 2026-07-27; rev 3, 2026-07-28 — ADR merged, phases 1–3 shipped, PM confirmation added (§3), outbound lane proposed (§8). Canonical decision text: docs/adr/0116-vendor-facing-job-reference-per-property.md on main, merged in PR #4720; the PM-confirmation follow-up is PR #4773, held for Fede's review. Evidence files on the Mac mini under ~/agents/006/po-training-data/.