VP Acceptance-Criteria Canon
v1.6 · 2026-07-12 (v1.6: OWN-1..4 two-layer ownership — canonical role assignment + tenant person→roles on the RBAC edge; granularity=cores · v1.5: THE JTBD GATE — canonical home, cite-jobs-or-don't-build, versioned evolution · v1.4: JTBD-10s = the completion bar · v1.1: ING-7/8 direct input, TP-CHAT-3 tool-using chat · v1.2: ARCH-1…4 one global Azure app, all-stakeholder full-VP ladder · v1.3: TIER-1…4 free-connect/paid-touch + ING-9 OKF interchange) · derived from: connections-design (#104), messages epic (#132), VP Choreography/Connections/Messages/Entity-Profile/Data .dc.html, po-vision-canon platform/data/tier docs, ROADMAP.md · verification results land in docs/vp-suite/vp-verifications.json citing AC IDs · board: VP-COMPLETION.html
The master AC: one shared world, role-projected. On /demo, distributor, processor, and producer read the same underlying objects (POs, threads, documents) through their own RBAC lenses, chase-linking to each other. A screen not on this spine is not done, however good it looks.
ARCH — platform shape
ARCH-1 … ARCH-4
| ARCH-1 | One global application on Azure serving every stakeholder type. Market/local differences (language, regulatory regimes, market data) are configuration and content — never code forks. Clay 2026-07-11 |
| ARCH-2 | Everything is a projection of the spine; the only question per stakeholder is how thick their lens needs to be. Every stakeholder type — distributor, processor, producer, lab, logistics/hub, customs, market releaser, trade finance, broker — is a paying, full-VP lens over time. The maturity ladder per stakeholder: unclaimed status page → claimed participant surface (shared-with-me, threads, action cards) → full lens (operate the business in VP). The ladder is simultaneously the acquisition funnel and the product. Clay 2026-07-11 |
| ARCH-3 | Sequencing, not scoping: distributor → processor → producer are driven to full-lens completion first (this campaign). Subsequent stakeholder lenses activate on the same primitives — each is "add a lens", never "build an app". The ING-1…8 pipeline, RBAC model, and spine objects are stakeholder-agnostic by construction. |
| ARCH-4 | Retail seams: US retail = producer-observer (live product: its own deployments and canon), DE pharmacy = shop (live at Inopha). Both connect via the same connect/share/status-object primitives; the seam is defined here, integration is its own campaign after the spine is real. |
Demo cast — fictional, canonical, used everywhere
The world (never use real company names)
| Entity | Role | Notes |
|---|
| Steinbach Distribution GmbH | Distributor (the tenant "you") | Mannheim; the Remexian-analog |
| Atlas Verde Farms | Producer | Portugal; GACP flower |
| Borealis Gardens | Producer | Canada; connected |
| Solterra Botanicals | Producer | Colombia; connection pending |
| Rheinwerk Pharma Processing GmbH | Processor (EU-GMP) | DE; QP on staff |
| Alpenlab GmbH | Processor | AT; not yet connected |
| Lindenhof-Apotheke | Pharmacy customer | Berlin |
| Falkenfracht Logistics GmbH | 3PL | Support services |
| Brückenkapital AG | Trade finance | Support services |
| Prisma Analytik GmbH | Lab | Support services |
People at these companies are also generated (fictional). All demo data, fixtures, screenshots, and walkthroughs use this cast — one world, forever.
TIER — free / paid model
TIER-1 … TIER-4
| TIER-1 | Free = connect + look. Touch = paid. Free tier: connect, be found, see what counterparties share with you (status pages, shared-with-me, threads received). Touching — creating, editing, sharing outward, running workflows, write-back — is paid. The exact free/paid line is TBD and is a deliberate per-action product decision, never improvised per screen. Clay 2026-07-11 |
| TIER-2 | Entitlements are configuration: every touch action passes one entitlement check at the same governed surface as RBAC (tier check beside the access check, audited the same way). Moving the free/paid line is a config change requiring zero code — this is what makes "TBD" safe to build against. |
| TIER-3 | World-class upgrade moments: the prompt appears contextually at the exact blocked touch ("you can see this PO slipped — answering Steinbach is on the paid tier"), states precisely what unlocks, one action to upgrade. Never nagware, never dark patterns. Pattern source: the cascade-pressure loop — each participant's inability to share their own data upward is the upgrade moment. VIRAL_ADOPTION_STRATEGY |
| TIER-4 | Why free: rapid adoption — 36,000 companies by end of 2026. The free tier is engineered for the viral loops: co-branded status pages to non-users (#117), inviter-vouch KYB, referral attribution (#119). Every free account is a future full-VP lens per ARCH-2. |
SPINE — cross-cutting interconnection ACs (apply to every touchpoint)
SPINE-1 … SPINE-8
| SPINE-1 | Every shared object (PO, thread, document, batch) has exactly one canonical record; every party sees a projection of it, never a copy. Changing status once updates every lens consistently. |
| SPINE-2 | Every status step shows a responsible party (company + person) and a working chase path — entity profile or Messages. No dead-end statuses. Choreography |
| SPINE-3 | Every share/grant/revoke/escalation is an append-only audit event (who shared what with whom, who approved); plain messages are ordinary rows. #132 |
| SPINE-4 | Revocation propagates immediately — no stale-window reads after a grant is revoked. #122 |
| SPINE-5 | Connect reveals nothing beyond public-register facts; data flows only through explicit Share valves. #104 |
| SPINE-6 | Status changes emit events consumable by feed/notifications, including to non-users via the semi-private status page (recipient-bound, teaser-vs-full split). #116/#117/#121 |
| SPINE-7 | Zero console errors and zero non-2xx on every screen, every state. #519 |
| SPINE-8 | Every screen degrades per-panel on missing data — never a blank screen, never fabricated values; derived figures carry confidence % until HIL-confirmed. |
RBAC — the one access model
RBAC-1 … RBAC-6
| RBAC-1 | 8 categories (Orders&POs · Pricing&margin · Compliance&CoA · Delivery&timeline · Logistics&shipments · Demand&pharmacies · Producer identity&cost · Financials&AR) × 4 levels (Edit/View/Informed/Hidden) — the only access vocabulary on the platform. |
| RBAC-2 | Cascade inheritance: stakeholder-group → company → role → person; a change ripples to everyone below without an override; overrides stick. |
| RBAC-3 | Role-archetype defaults match the design: e.g. producer lens = View orders/compliance/timeline/identity · Informed logistics · Hidden pricing/demand/financials; pharmacy lens = Hidden pricing/logistics/demand/identity/financials. VP Connections.dc |
| RBAC-4 | Sensitive categories (pricing · identity · financials) are approval-gated: granting stages a drafted request to the approver; nothing applies until approved. |
| RBAC-5 | Hidden is stripped everywhere: message drafts, status pages, exports, API projections — with per-message override possible only with a logged reason. VP Messages.dc |
| RBAC-6 | Demo/mocked authz implements the same decision surface the zed/SpiceDB backend will (#104 P0a) — swap-in, not rewrite; #121/#123 recipient-binding and claim/consent ordering carried as ACs now. |
| RBAC-7 | Per-leg economics: Hidden strips the other party's private economics — a party ALWAYS sees their own leg's terms and amounts (a producer sees their sale value and their payment schedule; a processor sees their fees). And stripped ≠ zero: a Hidden value renders as an absent section, never as €0k, "—", or a placeholder pretending to be data. Clay 2026-07-11 |
ING — ingestion → VP-native → write-back
ING-1 … ING-6
| ING-1 | VP owns no source data: every ingested entity carries provenance (source system, ingest time, mapping version). data.md |
| ING-2 | Multi-source conflicts route to the section's responsible human with a VP-drafted message + source links; item parks until answered. VP Data.dc |
| ING-3 | Confirmations cascade: one answer resolves its downstream records, with the cascade count shown and audited. |
| ING-4 | Bronze→silver→gold: users work the staging plane; production is touched in one audited place; trust % visible. |
| ING-5 | Data created/corrected in VP is first-class: over time VP is the write surface, and every correction is a staged write-back contract to the client system (ERP/D365/Collmex) — queued, auditable, reversible. Clay 2026-07-11 |
| ING-6 | Connector states are explicit per source (Connected / Not connected / Staged) on the entity's Connected-sources panel; "Connect X → unlock Y" is the only forward promise. |
| ING-7 | Direct human input is a first-class source: uploaded documents and manually entered data get the same treatment as system ingestion — provenance (person, time, method = upload/manual), classified on arrival ("born tagged"), same bronze→silver→gold pipeline, correctable, and eligible for write-back. Clay 2026-07-11 |
| ING-8 | Every uploaded document attaches to its entity (PO, batch, company, agreement) and carries an RBAC category (e.g. Compliance&CoA) — so the sharing valves and Hidden-stripping apply to documents exactly as to data. Unattached uploads sit in a triage queue, never a void. |
| ING-9 | OKF is the interchange spine of ingestion: sources normalize into OKF (one knowledge file per entity); confirmed truth exports as OKF; the backend OKF pipeline is Allan's lane with a working concept in hand. VP consumes and produces OKF and never blocks on a source landing — staged connectors + HIL carry the gap. VP Data.dc · Clay 2026-07-11 |
LENS — the /demo three-role workbench
LENS-1 … LENS-5
| LENS-1 | /demo/distributor, /demo/processor, /demo/producer render from ONE seeded world module — the canonical cast above — via one projection function per role. No per-lens data forks. |
| LENS-2 | Cross-lens consistency test: mutate a PO status in the world → all three lenses show the consistent projected result. |
| LENS-3 | Leak tests: producer lens never renders Steinbach's margin/landed cost; pharmacy-facing artifacts never render producer identity; assertions in CI. |
| LENS-4 | Every seeded field is schema-true: named for its vervana_app home (table.field) or explicitly tagged proposed — the proposed set IS the schema-change request to Allan, exportable as a list. |
| LENS-5 | The demo world is deterministic and versioned — fixtures, tests, screenshots, and walkthroughs all cite it. |
TP — per-touchpoint ACs
TP-PO · PO Tracker (first instance of the spine)
| TP-PO-1 | Spine view: producer → export gate → processor → import gate → warehouse; tokens carry PO#, party, status dot, ETA, chase link; gates accumulate blocked tokens with permit badges. |
| TP-PO-2 | Six parallel tracks (Commercial, Goods, Quality, Regulatory, Logistics, Finance) with per-step company assignment; regulatory handshakes and payment milestones bound to gate crossings. |
| TP-PO-3 | Token click → PO detail; chase → Messages thread for that counterparty with the PO in context. |
TP-MSG · Messages (context fabric)
| TP-MSG-1 | One canonical thread per counterparty across channels (in-app/email/WhatsApp as transports); thread header shows live PO status. |
| TP-MSG-2 | Context rail: shareable VP objects per-audience; guarded items show the guard reason; send = logged access grant ("granted access to N sources"), visible in the Connections access log. |
| TP-MSG-3 | Block-then-approve escalation when a draft includes a guarded artifact (#137); Hidden categories stripped from drafts per RBAC-5. |
TP-CON · Connections & Entity Profiles
| TP-CON-1 | Entity profile: Relationship (open items link to PO Tracker/Messages, history, documents) + Access matrix (8×4, cascade sidebar) + RACI for spine parties + People. |
| TP-CON-2 | Connection state machine (invited→pending→active→suspended→revoked); remove-company cascade-revokes in one click. |
| TP-CON-3 | Portable identity: VP-ID and relationship graph travel with the person; company data does not. |
TP-DATA · Data Foundation
| TP-DATA-1 | Ranked conflict queue across sections; each item: sources in disagreement, VP's read, Confirm / Merge / Needs-info actions per ING-2/3. |
| TP-DATA-2 | Audit trail per change (who, role, action, field from→to, cascade count, timestamp); trust meter to ERP-cutover threshold. |
TP-CHAT · Ask VP
| TP-CHAT-1 | Grounded per-object Ask-VP everywhere (PO, conflict, context item) — answers cite the object's actual data and deep-link to the owning screen. |
| TP-CHAT-2 | AI suggests, humans approve: any binding action drafted by VP requires explicit human confirmation; drafts are labeled as drafts. |
| TP-CHAT-3 | VP Chat is tool-using: it reads and acts through the same governed tool surface as the UI — query POs/inventory/financials, draft messages, file data corrections, attach documents. Every tool call passes the caller's RBAC projection, is audited, and hits the same approval gates. Chat can do anything its user could do in the UI, and nothing more — no side-channel. Clay 2026-07-11 |
THE JTBD GATE — checked by all work
GATE-J1 … GATE-J4
| GATE-J1 | Canonical home: the JTBD registry lives in docs/vp-suite/campaign/ on the campaign branch — jtbd-registry-roles.json (1,649 role-derived jobs, HITL dials verbatim) + the instrument (jtbd-scoreboard.html) + the analysis. One home; copies elsewhere are stale by definition. Clay 2026-07-11 |
| GATE-J2 | Every piece of work cites the jobs it serves. Specs, slices, PRs, and HITL pages name registry job IDs. Work that serves no registered job is flagged before building: either the job gets added through the amendment process, or the work doesn't happen. Screens are means; jobs are the requirement. |
| GATE-J3 | JTBDs are finite but evolve — through the loop, never silently. Add/edit via the instrument (Add-job / notes → export → ingest) or intake conversations (🔥 with source cited); every change is a dated commit Clay has accepted. Nothing enters or leaves the registry outside version control. |
| GATE-J4 | Evaluation is the gate's teeth: every job is scored on the anchored 0–10 rubric and carries its delegation dial (current → target HITL, progression verbatim from the role library). Campaign complete = shared cores + burning jobs at 10/10; the 159 designed trust-progressions are the VP's learning curriculum, promoted only on evidence. Scoring granularity = shared-core + burning (~450 evaluations), leaves as drill-down. Clay 2026-07-12 |
OWN — two-layer ownership (job → role → person)
OWN-1 … OWN-4
| OWN-1 | Canonical assignment (the standard): every JTBD is owned by exactly ONE canonical role (12 stakeholders × 6 president-roles). This map is portable — identical at all 36k companies — which is what makes it a gate and lets tenants be compared. Jobs are assigned to roles, never to people. Clay 2026-07-12 |
| OWN-2 | Tenant role-holding (the org chart): each company maps real people to canonical roles, many roles per person (small co: "Max does finance + operations" → Max holds both roles; large co splits them). A person inherits EVERY job of EVERY role they hold — that is their actual neck. The jobs never move; only who holds the role varies by tenant. |
| OWN-3 | Same edge as RBAC: the person→role assignment is the identical edge the 8×4 access cascade already uses (RBAC-2: person → role → access). Job accountability rides it too. Assigning Max to finance+operations grants both the job ownership AND the data access in one act — one assignment, both consequences. The delegation dial (HITL) is also held at the role level and inherited by the person. |
| OWN-4 | Demo personas (Doro Kessler = CEO, Lena Hartmann = Commercial…) are the 1:1 case of OWN-2. The instrument's one-neck rollup rolls up at the canonical-role level; a tenant view rolls the same jobs up to whichever person holds those roles. |
Board mapping
How gates consume this canon
parity gate evidence cites the design ref + TP-* ACs · resilience cites SPINE-8 fixture tests · journeys cites SPINE-7 (J1–J4) · schema-wired is registry-derived, with LENS-4 proposed fields as the schema backlog · every vp-verifications.json entry's evidence names AC IDs. And above the gates sits the JTBD scoreboard (docs/vp-suite/campaign/jtbd-scoreboard.html): the campaign is complete only when every stakeholder job scores 10/10 on the anchored rubric — screens green is necessary, jobs at 10 is sufficient. The canon is amended only via the accept/redo loop; amendments are dated.
Amend via "amend the canon: …" · lives at docs/vp-suite/AC-CANON.html on the completion-board branch · Clay ⇄ Claude · 2026-07-11