Home: All V2 Specs · Foundation: Data System (UVP)

Global Rules

Cross-cutting product rules derived from the spec sheets (241 rules). These govern every feature regardless of mode.

Relationship | Campaign | Petition

UVP Single Source / Data Integrity

• Across all features, route every voter read and write through the single Unified Voter Profile (UVP) — never duplicate or copy voter data between modes, since modes are views, not separate records.

Skills Setup / Process

• Before writing any feature code, always ensure the relevant politogy-ai-skill-vrm-* skills are installed in .claude/skills/ — if a required one is missing, clone it from github.com/The-Portland-Company first and treat its absence as a blocker, never optional.

Skills / Data

• When writing UVP or voter-data code, never proceed without politogy-ai-skill-vrm-data-provenance and politogy-ai-skill-vrm-exposure-control installed and followed.

Skills / Auth

• When writing authorization, role, or tier-gating code, never proceed without politogy-ai-skill-vrm-rbac installed and followed.

Skills / Messaging

• When writing outbound SMS, email, or voice code, never proceed without politogy-ai-skill-vrm-messaging-compliance installed and followed.

Skills / Identity

• When writing import, identity-match, or merge code, never proceed without politogy-ai-skill-vrm-identity-resolution installed and followed.

Skills / Offline

• When writing offline or field-capture code (Field Canvassing, Sign Mapping), never proceed without politogy-ai-skill-vrm-offline-sync installed and followed.

Data Ownership / Security

• Treat the UVP and all its data layers as Politogy-owned, not customer-owned — customers only ever receive a curated view, never the full underlying record.

Data Priority / Data Integrity

• Always resolve conflicting field values by strict priority — user-entered wins, then voter file baseline, then enrichment fills gaps only when nothing higher-priority exists.

Non-Destructive Writes / Data Integrity

• Never overwrite voter-file or user-entered data — write higher-priority values as the new primary and demote the prior value to a preserved alternate that is never deleted.

Provenance / Data Integrity

• Always record full provenance (source, timestamp, confidence, superseded-by) on every value written to a UVP.

Provenance Privacy / Security

• Never expose provenance metadata or internal data layers to customer-tier users — provenance is internal infrastructure only.

Two-Tier Enforcement / Security

• Enforce the two-tier exposure model at the data layer, not the UI — customer-tier users must only receive fields Politogy has explicitly exposed for their tier and account scope.

Seamless Exposure / Privacy

• Never reveal the existence of hidden fields to customer-tier users — omit them entirely rather than showing blank values, locked icons, or redaction markers.

Real-Time Exposure / Security

• Make exposure-control changes take effect in real time — a Politogy admin changing a field’s exposure level must reflect on the next profile load with no deploy, cache flush, or wait.

Tenant Isolation / Security

• Always isolate customer accounts — one account’s relationship data, notes, tags, and custom fields must never be visible to another customer account.

Global Field Immutability / Data Integrity

• Never let users rename, retype, redefine, or delete global fields — their canonical name, type, and validation rules are Politogy-locked and immutable.

Custom Field Namespace / Data Integrity

• Always store user custom fields in a separate namespace from global fields, scoped to the creating account, and tagged with full provenance.

Field Promotion / Data Integrity

• Treat field promotion (custom to global) as a one-way, data-preserving operation — once global, a field stays global and all existing custom data migrates without loss.

Import Merge Scope / Data Integrity

• Make voter-file and enrichment merges touch only Identity Core, Contact Info, Geographic, and Vote History — never Relationship, Campaign, Petition, or Aggregate Intelligence data.

No Hard Delete / Compliance

• Never hard-delete a voter record or user-generated data — archive non-active records (inactive, deceased, moved, merged) so they stay searchable and feed Aggregate Intelligence indefinitely.

Computed Fields Read-Only / Data Integrity

• Treat computed/AI-generated fields as read-only for all users including Politogy admins — only system processes may write them, and they never overwrite user or voter-file data.

AI Provenance / Data Integrity

• Always store AI-generated values in the Aggregate Intelligence layer with model name/version, input lineage, confidence, timestamp, and refresh cadence — archiving old values on model upgrades rather than deleting them.

Event Stream / Data Integrity

• Emit a change event on every UVP write from any source so downstream AI and intelligence processes can consume incremental changes without rescanning the database.

Export Scope & Audit / Compliance

• Constrain every customer-tier export to only that user’s visible, in-scope data and log each export and extraction with user, timestamp, filter criteria, and record count.

Import Matching / Data Integrity

• Never auto-create UVPs from customer imports — match supplemental imports against existing UVPs and flag unmatched records for review.

Criteria Truth / Data Integrity

• While writing Tribes code, always treat the structured criteria expression as the source of truth and the natural-language prompt as merely an authoring interface — never persist a Tribe without its structured criteria.

Failure Surfacing / UX

• While interpreting Tribe Builder prompts, never silently drop a constraint you cannot parse — always surface the failure and ask the user to clarify.

Refinement Chaining / UX

• While processing Tribe Builder input, always interpret each new prompt as a refinement of current state unless the user explicitly starts over.

Issue Stance Primitive / Data Integrity

• While modeling issue stances, always store them as the first-class issue_stances UVP substructure with full per-source provenance — never as a flat custom-field value.

Stance Consolidation / Data Integrity

• While consolidating issue stances, always let the most recent strong signal win and reduce confidence on conflicting signals — never delete prior sources.

Issue Registry / Compliance

• While mapping issues from natural language, always resolve synonyms through the Politogy-controlled canonical issue registry — never let customer accounts mint custom issues.

Petition Pipeline / Data Integrity

• While handling a petition signature, always perform two separate writes — one to the Petition-Sourced Tribe membership and one to the signer’s UVP issue_stances — never collapse them into one.

Signature Withdrawal / Data Integrity

• While invalidating a withdrawn petition signature, always remove Tribe membership and mark the stance source invalidated for audit — never hard-delete the source from history.

Cross-Mode Resolution / Compliance

• While resolving a cross-mode Tribe consumption, always auto-intersect against the consuming mode’s authorization or opt-in scope — never error and never silently include out-of-scope members.

Two-Tier Boundary / Privacy

• While exposing Tribe data, always confine customers to their own Tribes, members, and stance distributions — cross-account patterns belong only to Politogy’s anonymized aggregate tier.

Performance Caching / Data Integrity

• While serving Tribe membership, always use hot/cold caching with indexed criteria evaluation and async recomputation — never recompute full membership synchronously on every read.

Send Safeguard / UX

• While guarding a send to a Tribe, always warn when membership shifted more than ~5% since last view and offer a refresh before action.

Provenance / Compliance

• While recording Tribe operations, always provenance-track creation source, criteria-change history, static membership edits, and every action use for audit.

App Isolation / Architecture

• Build each Mode>Feature as its own standalone app on its own subdomain with its own dedicated Supabase project — never fold two features into one app or one database, so a breach or load spike in one is contained to that feature.

App Isolation / Security

• Never share a Supabase project, service-role key, or storage bucket across two feature apps — each app gets its own project, keys, and RLS so cross-feature data exposure is structurally impossible.

App Isolation / Data Layer

• When one feature app needs another’s data, go through the shared UVP data-layer API and OIDC identity — never reach directly into another app’s Supabase tables.

Subdomain Convention / Architecture

• Give every feature app a predictable subdomain pair: app .politogyvrm.com (prod) and -staging.politogyvrm.com (staging); auth lives at auth.politogyvrm.com / auth-staging.politogyvrm.com.

Auth / SSO

• Always delegate authentication to the politogy-auth OIDC provider — never build a per-app password store or collect Politogy passwords in a feature app; the IdP (Supabase Auth behind auth.politogyvrm.com) is the only credential store.

Auth / OIDC Discovery

• Configure OIDC clients by fetching the discovery document at /.well-known/openid-configuration — never hardcode authorize/token/jwks/userinfo endpoint paths in app code.

Auth / PKCE

• For browser/SPA (public) clients, always use the authorization-code flow with PKCE S256 and a random state — the authorize endpoint rejects public clients without it.

Auth / Token Verification

• Always verify the id_token signature offline against the IdP JWKS (RS256) and confirm aud == your client_id before starting an app session — never trust an unverified token.

Auth / JIT Provisioning

• On a user’s first sign-in, JIT-mirror them into the app’s own Supabase from the /oauth/userinfo claims keyed by the stable sub — never copy identity attributes (name, phone, sms_opt_in, signature) into app tables as the source of truth; they live only in the IdP’s auth.users metadata.

Auth / Client Registration

• Register every app as a client row in the IdP’s oauth_clients table with exact redirect_uri matching (scheme, host, port, path); mark SPAs is_public=true (no secret), server apps confidential with a hashed secret.

Auth / Env Config

• Drive OIDC config from per-environment env vars (OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_REDIRECT_URI, OIDC_SCOPE, and OIDC_CLIENT_SECRET for confidential clients) — staging points at auth-staging.politogyvrm.com, production at auth.politogyvrm.com.

Auth / Refresh Tokens

• Use the refresh_token grant for session continuation and expect refresh tokens to rotate on every use; request the offline_access scope to receive them, and store tokens only server-side or in secure storage.

Environments / Parity

• Always maintain both a staging and a production deployment of every feature app, each wired to its own environment-matched Supabase project — staging app to staging DB, prod app to prod DB.

Environments / Isolation

• Never let a staging app read or write a production database (or vice versa); resolve all DB URLs, keys, and OIDC issuers from environment config, never hardcoded.

Environments / Supabase Branches

• Use Supabase branches for ephemeral preview/PR databases and separate Supabase projects for the durable staging and production environments — do not test schema changes against the production project.

CI-CD / PR-First

• Ship every change to every app through a pull request into a protected production branch — never commit or force-push directly to production; AI agents branch as codex/.

CI-CD / Tag-Driven Deploy

• Trigger deploys only by force-moving the deploy-staging / deploy-production tag (npm run release:staging|production), never by ad-hoc pushes; the production tag must point at the current origin/production commit.

CI-CD / Pre-Commit Hooks

• Every app installs the unified pre-commit suite: gitleaks + detect-secrets, eslint, type-check, critical smoke tests, file-hygiene checks, and Conventional Commits enforcement — a commit that fails any of these must not land.

CI-CD / Security Scans

• Run the same CI security gate on every PR for every app: gitleaks, trufflehog (verified), and npm audit; surface findings as a blocking failure, not a warning.

CI-CD / Shared Pipeline

• Reuse one shared CI/CD template (reusable GitHub Actions workflow + shared pre-commit config) across all feature-app repos so quality, security, and deploy steps stay identical — do not hand-roll a divergent pipeline per app.

CI-CD / Migrations Ship With Code

• Always ship database migrations in the same release as the code that depends on them and apply them during deploy (db:push); never deploy code expecting new schema without the migration, and never skip a migration step.

CI-CD / Health Checks

• Expose a /api/health (and /health) endpoint on every app and gate deploy success on a post-deploy health probe — a deploy that doesn’t pass health checks is a failed deploy.

Tech Stack / Hosting

• Default frontends to Cloudflare Pages and edge/API logic to Cloudflare Workers whenever possible; use Railway only for long-running backend services that can’t run on Workers.

Tech Stack / Storage

• Use Cloudflare R2 for object/file storage (no egress fees) rather than other blob stores; keep bucket access scoped per app.

Tech Stack / Data Platform

• Use Supabase for database, auth backing store, and edge functions; deploy edge functions individually honoring each function’s verify_jwt config (use the —no-verify-jwt wrapper) so bulk deploys never silently re-enable JWT on webhook receivers.

Tech Stack / Runtime Pinning

• Pin Node and toolchain versions consistently across apps (Node 20 in CI, Node 24 in deploy, Deno for backend/edge) so local, CI, and deploy environments don’t drift.

Secrets / Security

• Never commit secrets, keys, or .env files — load all credentials from environment/secret stores (GitHub Actions secrets, Cloudflare/Railway env, 1Password) and rely on the secret-scanners to block leaks.

RLS / Security

• Enable Row Level Security on every table in every app’s Supabase and write policies keyed to the OIDC sub/org — never rely on the client or service-role key to enforce per-user access.

Config / Security

• Never hardcode a Supabase project ref, URL, or anon/service key in app code; resolve them from env and keep the check-no-hardcoded-supabase guard green.

Observability / Reliability

• Wire centralized error logging (and Sentry where available) into every app, scrubbing PII before it leaves the app; do not let a feature app fail silently.

Dependencies / Security

• Keep dependencies current via the shared Dependabot config and treat critical/high npm-audit findings as release blockers — do not deploy with known critical vulnerabilities.

Relationship | Campaign

Compliance

• While writing SMS send code, always resolve the compliance ruleset server-side from the active mode (Relationship vs Campaign) — never let the client choose which rules apply.

STOP / Compliance

• While building the message composer, always auto-append the configurable STOP/compliance line and never expose a way to disable it.

Consent / Compliance

• While handling Relationship Mode sends, always exclude recipients lacking a confirmed SMS opt-in record and surface the excluded count with reasons — never silently include them.

Opt-Out / Compliance

• While processing inbound STOP keywords, always opt the recipient out within ~5 seconds, send confirmation, and block all future sends across every campaign in the account.

Limits / Data Integrity

• While capping manual recipient input, always limit pasted lists to 10,000 and CSV uploads to 50,000 (chunked async) — beyond that require a Tribe.

Quiet Hours / Compliance

• While scheduling or sending, always enforce quiet hours (default 9pm-8am recipient local time) and auto-shift scheduled sends out of the quiet window with a warning.

Routing / Data Integrity

• While assigning sender numbers in a multi-number campaign, always use deterministic sticky assignment (hash of recipient phone + campaign ID) so a recipient always sees the same number and replies route correctly.

Pre-Flight / Compliance

• While committing a campaign, always run the final compliance scan (re-validate opt-in, quiet-hours math, 10DLC standing) and block commit on failure — never let Tech Check be skipped.

Frequency / Compliance

• While enforcing send frequency, always default-cap marketing messages at 3 per recipient per week and 5 per recipient per day across all automations combined.

Provenance / Compliance

• While writing opt-in records, always persist full provenance (source, timestamp, consent language, IP/device, single vs double opt-in) as the legal audit trail.

Webhooks / Data Integrity

• While processing Telnyx webhooks, always acknowledge within 10s, verify the signature, and process delivery/inbound events asynchronously.

Architecture / Data Integrity

• While building the messaging layer, always route through a provider abstraction (Telnyx as the V1 implementation) rather than hard-coding the vendor.

Cost / Data Integrity

• While deducting send cost, always use real-time accounting with optimistic locking and halt sends on insufficient balance — never send beyond available credit.

Inbound / Data Integrity

• While handling inbound from an unknown number, always create a phone-only UVP record and open a conversation thread labeled until matched — never drop the message.

Permissions / Security

• While gating send and number-management actions, always restrict Send and Numbers management to Admin/Manager, but allow any user with conversation access to pause a live send.

Insight Over Reporting / UX

• While building any dashboard metric, never ship a bare number — every metric must carry context (trend, baseline, comparison, or AI annotation).

Mode Architecture / UX

• Always preserve the same five tabs (Pulse, Network, Relationships, Demographics, Opportunities) across both modes — Campaign Mode changes orientation, emphasis, and overlays, never the tab structure.

Action Over Observation / UX

• Always make every actionable surface (opportunity, person, segment, insight) one-click convertible to a Next Move with an owner/deadline/channel/closeout contract.

Aggregate Attribution / Privacy

• Always attribute Aggregate Intelligence (cross-account) insights with their basis (e.g. ‘based on N similar accounts’) and never surface them below the privacy floor of 10 similar accounts.

Account Adaptation / Data Integrity

• Always flex labels, emphasis, and AI tone by account type (campaign vs. influencer) over one identical data model; never fork the schema per account type.

Persistent AI / UX

• Always keep AI as a persistent layer (Insight Bar, inline annotations, Strategic Analyst) on every tab — never a separate AI destination tab.

AI Honesty / Compliance

• Always surface confidence levels when low and never present a low-confidence pattern as fact; the Strategic Analyst answers from live account data, citing specific metrics.

Source-Agnostic Donations / Data Integrity

• Always treat donation data as source-agnostic — the user must not be able to tell from the dashboard whether a figure came from the Politogy portal, WinRed, Anedot, or CSV import.

VRM Verified / UX

• Always treat VRM Verified match rate and UVP completeness as first-class dashboard metrics with an obvious lever to improve them — they reinforce the core value proposition on every login.

No Duplication / UX

• In Campaign Mode, keep the Demographics tab as an executive summary that hands off to Battleground for deep gap/precinct analysis — never duplicate Battleground’s operating tools on the dashboard.

Permissions / Security

• Always honor customer-tier dashboard permissions (Admin/Manager/Field/Viewer) including scope limits and Viewer’s read-only no-Next-Move restriction; keep tier-gating an account-layer overlay, not dashboard logic.

Opportunity Feedback / Data Integrity

• Always track dismissed Opportunities to teach AI ranking and allow restoration; never hard-delete a dismissed opportunity.

Accessibility / UX

• Never let color be the sole carrier of meaning for trend or status, and keep AI annotations screen-reader accessible with density toggles and full keyboard navigation.

Relationship

Mode Wall / Privacy

• While selecting recipients in Relationship Mode, always restrict the audience to opt-in contacts and hard-error any segment that attempts to query the voter roll.
• While exposing cross-mode data, always gate engagement-data availability to Campaign Mode behind an explicit cross-mode permission flow — never auto-share it.

Deliverability / Compliance

• While configuring sender identity, always require a verified domain and block free-provider (Gmail/Yahoo/Outlook) from-addresses.

Compliance

• While composing any email, always auto-inject the one-click List-Unsubscribe header and the CAN-SPAM physical address footer — never let a send omit them.

Unsubscribe / Compliance

• While processing unsubscribes, always honor them within minutes and add the address to the account suppression list applied to every future send.

Credits / Data Integrity

• While deducting Broadcast Credits, always consume credits on dispatch (not at schedule time), hard-block sends when insufficient, and let in-flight batches complete.

Block Schema / Data Integrity

• While rendering historical emails, always pin a block’s schema version to the email at draft creation and keep the renderer backwards-compatible with all shipped versions.

Security

• While ingesting media or custom content, always sanitize uploaded assets (especially SVG) before storage or delivery.

AI / UX

• While exposing AI features, always treat AI output as a reviewable suggestion the user edits and never auto-send AI-generated content.

Validation / UX

• While gating navigation, always require verified Sender Information and at least one recipient segment before allowing Send & Automate.

A/B Testing / UX

• While computing A/B tests, always disable A/B in the UI below the minimum per-variant audience (proposed 1,000) and display statistical significance.

Retention / Data Integrity

• While retaining email data, always archive sent emails instead of deleting them and keep engagement events per the account retention policy (default 7 years).

UVP-as-view / Data Integrity

• While writing Contacts code, never duplicate UVP data into a contacts table — always render contacts as a view over the UVP keyed by the account_claim relationship.

Verification / Data Integrity

• While writing Contacts code, never let a user manually set or edit VRM Verified status — verification tier is computed by Politogy from evidence and pushed read-only.

Bulk edit safety / Data Integrity

• While writing All Contacts bulk-edit code, never allow bulk editing of Identity Core (voter-file) or Vote History fields — keep them read-only at the customer tier.

Channel consent / Compliance

• While writing Quick Action code, always disable Text/SMS (and channel actions) for contacts opted out of that channel, with a tooltip explaining why.

Multi-match / Data Integrity

• While writing import code, always quarantine rows that match two or more existing UVPs for Duplicates-tab review rather than auto-merging them.

AI mapping / Data Integrity

• While writing import code, always let the AI only suggest field mappings — never auto-import; the user must adjudicate ambiguous mappings.

Field namespace / Data Integrity

• While writing import code, always treat a created custom field as joining the shared account namespace — never create form-only or import-only parallel fields.

Field deletion / Data Integrity

• While writing custom-field code, never hard-delete a custom field that has data on any UVP — block deletion permanently and explain why in a tooltip.

Merge lifecycle / Data Integrity

• While writing merge code, never destroy a losing record — convert it to a Merged-state UVP pointing to the survivor and keep the merge reversible for 14 days.

Provenance / Data Integrity

• While writing any contact mutation, always record provenance (source, timestamp, user, prior value) and never overwrite a value silently.

Soft delete / Security

• While writing Bulk Delete code, never hard-delete UVPs — archive only, and gate the action to Admin role.

Export exposure / Privacy

• While writing Export code, always enforce the account’s data-exposure rules so tier-gated and internal fields never leave the platform.

Enrichment gating / Privacy

• While rendering the Contact Card, always gate Enrichment fields behind a tier unlock prompt and never display purchased data the account has not unlocked.

Edit priority / Data Integrity

• While writing Contact Card edit code, always demote the prior voter-file value to a provenanced alternate when a user edits Contact Info — never discard it.

Field library / Data Integrity

• While building forms, never define fields on the form itself — a form only selects existing global or account custom fields from the Field Library.

Field removal / Data Integrity

• While writing form-edit code, removing a field from a form must never delete the field or its UVP data — only stop exposing it on that form.

Duplicate prevention / Data Integrity

• While writing custom-field creation, always run the internal-name and semantic-label duplicate check and prompt reuse before allowing a new field.

Identity match / Data Integrity

• While writing the submission pipeline, always run the 4-step identity match (email, phone, name+address, name+DOB) and quarantine multi-match submissions for review.

Consent gate / Compliance

• While writing form publish code, never allow a form to go Live without consent configuration complete, and require TCPA disclosure when a Phone field is present.

Type immutability / Data Integrity

• While writing field-type code, never allow changing a custom field’s type once any submission has written data to it.

Option lifecycle / Data Integrity

• While writing option-edit code, never delete a dropdown/radio/checkbox option that has submission data — only deactivate it.

Write provenance / Data Integrity

• While writing the UVP write step, always preserve prior field values as provenanced alternates and record form ID, submission ID, IP, timestamp, source URL, and consent record.

Form lifecycle / Data Integrity

• While writing form-deletion code, never hard-delete a form that has submissions — archive only, since submissions reference it as UVP provenance.

Atomic write / Data Integrity

• While writing the validate step, never persist a partial submission — reject invalid or consent-missing submissions atomically with a user-facing error.

Exposure control / Privacy

• While building the Field Library, never surface Politogy-internal fields, embargoed/internal-only global fields, other accounts’ custom fields, or system metadata to the user.

Permissions / Security

• While writing custom-field creation gating, always restrict it to Admin and Manager roles to protect the account’s custom field namespace.

Runtime / UX

• While writing CTA runtime code, always render in a scoped CSS namespace using vanilla JS and keep the bundle under 30KB gzipped — never let host-page styles leak in or pull in heavy dependencies.

Visitor ID / Privacy

• Always set and read the Politogy Visitor ID as a first-party cookie scoped to the customer’s domain only — never share, sell, syndicate, or carry it cross-domain in V1.

Conversion Merge / Data Integrity

• On any conversion, always merge the Visitor ID into the resulting UVP so the full pre-conversion behavioral history attaches retroactively via web_engagement_profile.

Consent / Compliance

• Always support a host-callable consent API (window.vrm.consent.granted/withheld) so the Runtime can gate the Visitor ID cookie behind the site’s GDPR/CCPA consent layer.

Trigger vs Targeting / Data Integrity

• Always treat Trigger (when to fire) and Targeting (whether to fire) as distinct concepts — a CTA fires only when its one Trigger and all stacked Targeting rules are satisfied.

Frequency / UX

• Always enforce frequency-cap and dismissal-memory defaults (3 impressions/visitor/24h; suppress 7 days after dismissal) unless explicitly overridden per CTA.

Inline Capture / UX

• Never allow more than two Inline Fields on a single CTA — route richer capture to a linked Form instead.

Accessibility / UX

• Always respect prefers-reduced-motion by falling back to Fade or No Animation, keep CTAs keyboard-dismissible (ESC/Tab), label inline fields for screen readers, and validate color contrast at save time.

Embedding / Data Integrity

• Never bind an embedded Survey/Form reference that points at a non-Live object, and never let a Live CTA change its embedded reference once data has been captured against the original.

Partial Capture / Data Integrity

• Always persist embedded-Survey partial responses on each answered question (linked to the Visitor ID), not only on completion, so abandoned mid-flight answers are still captured.

Versioning / Data Integrity

• Always bucket impression and conversion analytics by CTA configuration version so edits do not contaminate prior performance data.

A/B Testing / Data Integrity

• Never declare an A/B winner below 100 conversions per variant or under 95% confidence — show ‘Need more data’ instead, and keep variant assignment cookie-sticky for the test duration.

Permissions / Security

• Always gate the act of pushing a CTA Live (and A/B authority) to Account Admin and Manager roles only.

Architecture / Data Integrity

• Always model a Survey as a deployed Form reusing the same builder, field library, and submission pipeline — never fork a parallel codebase or a separate custom-field namespace.

Positioning / Compliance

• Never present Survey results as representativeness — phrase outputs as ‘X% of respondents answered Y’, never ‘X% of voters believe Y’, and never add methodology scoring, finding-strength tiers, or strategic memos.

Anonymous Mode / Privacy

• In Anonymous mode, always sever the response-to-UVP link architecturally: block identity fields from the canvas, hide the per-response table, export aggregate-only, and record only an engagement event on the UVP.

Identity Lock / Data Integrity

• Always lock the Survey identity mode immutable at the Draft/Scheduled to Live transition — never allow it to change once Live.

Instrument Stability / Data Integrity

• Once a Survey is Live with at least one response, never allow adding, removing, reordering, or modifying questions, changing audience, or shortening the close date — clone for changes.

Lifecycle / Data Integrity

• Never re-open a Closed Survey — only allow cloning into a new distinct Survey with a fresh Deployment Plan and separate results.

Tokens / Security

• Always issue cryptographically secure single-use tokens for Targeted Invite links, expire them at Survey close, invalidate on response, and stop reminders once a contact responds.

Anti-Abuse / Security

• When a Survey enables Public Distribution, always default CAPTCHA, honeypot, rate limiting, and one-response-per-session/IP on.

Consent / Compliance

• Always exclude contacts who opted out of a Survey from future Survey invites by default, allowing only an explicit per-Survey override for legally-required communications.

Upgrade Funnel / Data Integrity

• Always surface low-cell-size cross-tabs with an explicit ‘low confidence n=X’ caveat that doubles as the Polls upgrade prompt — never present small-n cells as conclusive.

Campaign

Two Writes / Data Integrity

• While handling a pin drop, always write two architecturally distinct records — the SignPlacement asset entity and the UVP Supporter Layer event — never collapse them into one structure.

Frictionless Capture / UX

• While building the mobile pin drop, always keep it three taps and never block save on UVP matching — supporter resolution happens invisibly server-side after sync.

Offline-First / Data Integrity

• While saving placements, always persist offline first and sync later, treating an offline pin as exactly as valid as an online one.

Timestamp Fidelity / Data Integrity

• While preserving offline truth, always store the device-local capture timestamp separately from the server sync timestamp.

Geofence Warn / UX

• While validating geofence, always warn and require confirmation on out-of-district pins — never block the save.

Auto-Match / Data Integrity

• While running UVP resolution, always write low-confidence matches immediately as unverified and route them to the Manager Review Queue — never silently drop signal for lacking confidence.

Billboard Exclusion / Data Integrity

• While placing billboards, never attempt UVP matching or write a supporter event — commercial structures rarely have voter owners.

Event Persistence / Data Integrity

• While transitioning placement lifecycle, always keep the supporter event intact through recovered/lost/stolen/damaged states — only a hard-delete supersedes it with a corrective event.

Soft Delete / Security

• While deleting placements, always default to soft-delete with deleted_at, reserving hard-delete for Account Admin and Politogy roles.

Confirm Gating / Security

• While gating supporter-match confirmation, always restrict it to Manager-and-above roles — it writes to UVP-canonical data and is never a volunteer action.

Anonymization / Privacy

• While exposing cross-account sign-host data, always anonymize at the campaign level and gate behind the Intelligence Product entitlement — never reveal which campaign a voter previously hosted for.

Role Visibility / Privacy

• While hiding supporter-match indicators, always restrict match-status badges, linked-UVP details, and supporter filters to Manager-and-above — keep them off the volunteer field surface.

Telemetry / Data Integrity

• While building any Sign Mapping surface, always emit placement, lifecycle, match, review, and recovery events to the Aggregate Intelligence telemetry stream from day one, even where analytics UIs are deferred.

Predictive Dialer / Compliance

• While writing Phone Banking dialer code, never implement predictive dialing — omit it from the Dialer Mode enum entirely (click-to-call V1, preview V1.5).

Compliance Architecture

• Always enforce TCPA, DNC, calling hours, recording consent, and identification disclosures at the system layer; never rely on a checklist or trust the Caller to self-comply.

Dialer Guard / Compliance

• Always disable the dial action when a voter is on any DNC (federal/state/internal/platform) or outside legal calling hours for their local time zone; never let such a call be placed.

List Exclusion / Privacy

• Always exclude DNC and ineligible voters silently at list-build time, surfacing only aggregate exclusion counts; never expose excluded voter names to the Manager.

Posture Lock / Data Integrity

• Always lock Posture (A vs B) at Session creation; never allow mid-Session Posture switching in V1, as it corrupts poll-grade data.

Poll Integrity / Data Integrity

• Always constrain Posture A Contact Outcomes to the frozen poll instrument plus fielding outcomes; never let customers add ad-hoc outcomes to a poll-fielding session.

Recording Consent / Compliance

• Always require the recording-consent prompt to be delivered before recording starts in two-party-consent states; never let recording initiate without the acknowledged prompt.

Voicemail Drops / Compliance

• Always keep outbound voicemail drops off by default and landline-only when enabled; never drop to cell-phone voicemail in V1.

Script Pre-Check / Compliance

• Always reject any Script that fails the phone compliance pre-check (missing disclosures, opt-out, or consent language); never allow it to attach to a Phone Session.

Script Versioning / Data Integrity

• Always treat scripts as immutable once attached to a Live Session, versioning edits as N+1; never mutate the script a Live Session is running on.

Cross-Channel Ledger / Data Integrity

• Always write a Cross-Channel Contact Ledger entry for every Call Attempt and honor cooldown checks; never place a contact that ignores cross-channel double-contact prevention.

Runtime DNC / Compliance

• Always propagate a runtime do-not-call request to internal DNC and the account’s other channels, but never auto-add the voter to federal/state/platform DNC.

VWPP / Privacy

• Always accumulate Caller scoring into the single cross-account VWPP on the unified Volunteer Worker; never expose the unified entity to customers (show only the Caller slice).

Caller Permissions / Privacy

• Always restrict a Caller to the voter card for their active Session only, with no search, export, cross-Caller notes, or Manager dashboard access; never loosen the Field Volunteer permissions.

Caller Identity / Privacy

• Always originate outbound calls from the provisioned campaign number and never expose a Caller’s personal number to the voter.

Calling Hours / Compliance

• Always constrain Session windows to legal calling hours across every time zone in the list so no Caller can be scheduled to dial illegally; never permit a calling-hours override in V1.

Door Visit Event / Data Integrity

• While writing canvassing capture code, always store each door knock as one immutable Door Visit Event keyed by a client-generated UUID — never overwrite, merge, or delete a prior visit.

Capture Mode / Data Integrity

• Always attach a Capture Mode (Self-Report / Observation / Verified) at the field level to every outcome, note, and door-fielded poll response — never let a captured datum reach Aggregate Intelligence untagged.

Pre-Shift Sync / Safety

• Never start a canvasser shift without a successful mandatory pre-shift sync — the shift cannot begin offline.

Sync Priority / Safety

• While writing offline-sync code, always push in safety-first priority order: panic events, then incident reports, then do-not-knock flags, then door events, GPS, and media last.

Panic Button / Safety

• Always deliver the panic button as a hot path that records locally then retries across every channel (cellular, WiFi, SMS fallback) until transmission is confirmed — never defer it to normal sync.

Do-Not-Knock / Compliance

• Always re-check do-not-knock and unsafe-property flags at door-card display time, not just at list generation — never assume the generated list is still current.

Safety Intelligence / Privacy

• Always surface cross-account safety warnings to canvassers as structured severity and reason category only — never expose raw free-text observations, which stay Politogy-tier.

Optimization Constraints / Safety

• While building optimization or assignment, always treat geofence, do-not-knock, and Do-Not-Approach exclusions as hard constraints — never route or assign a door that violates them.

Walk List / Data Integrity

• Always treat a walk list as a versioned, first-class longitudinal entity with a methodology abstract — never as a transient address list, and freeze it immutable once Live.

Poll Tokens / Security

• Always batch-issue canvas poll tokens scoped to (canvasser, walk list, door) at pre-shift sync and expire them at shift end — never issue just-in-time like SMS fielding.

IP Boundary / Security

• Always enforce the CPP and optimization-algorithm IP boundary at the data-write and query layer, never the UI — customers see tier-gated outputs, never the scoring model or weights.

GPS Consent / Privacy

• Always require explicit, granular, revocable GPS consent and default new campaigns to Verification-only mode — never capture a continuous trail without dual opt-in.

Flag Moderation / Safety

• Always route every Do-Not-Approach flag through the Politogy moderation queue and apply time-decay to flags — never let an uncorroborated single flag permanently exclude a door.

Data Provenance / Data Integrity

• While storing canvasser-captured values, always prefer them over voter-file values on conflict while preserving full provenance — never silently overwrite source data.

Posture Lock / Data Integrity

• Always lock a Session’s Posture (Poll-Fielding vs Contact Operation) at creation and route data accordingly — never let a Contact Operation write to the four-dimensional poll scoring model.

Contact Ledger / Data Integrity

• Always write every contact attempt on every channel to the append-only Cross-Channel Contact Ledger and consult it before assignment and in-session — never prevent double-contact by convention alone.

DNC Propagation / Compliance

• Always propagate a voter opt-out or do-not-contact across every channel via the Ledger — never let a campaign door-knock someone who opted out by phone.

Worker Portability / Privacy

• Always accumulate one continuous Volunteer Worker VWPP across all accounts and channels, exposing customers only their account slice — never expose account-by-account cross-account breakdowns.

Script Versioning / Data Integrity

• Always treat the Script Object as immutable once attached to a Live Session — never edit in place; editing creates version N+1 while the Live Session continues on version N.

Worker Permissions / Security

• Always restrict Field Volunteer roles to assigned-Session voters and Script-required UVP fields only — never allow workers to search, export, or view another worker’s notes.

Preserve All / Data Integrity

• Always preserve conflicting captures across workers and channels rather than averaging or resolving them — never delete captured field data; let Aggregate Intelligence interpret.

Audit Trail / Compliance

• Always require every contact attempt, disposition, override, and Session state transition to be auditable and timestamped — never apply a manager override to AI artifacts without logging it.

Finding Tiers / Data Integrity

• While writing Polling Engine analysis code, never let the UI or user input directly set or upgrade a finding’s strength tier — tiering is automatic, finding-level, and AI-controlled.

Override Carriage / Compliance

• While building any override path (question objection or tier), always make it friction-laden, log it with user/timestamp/AI objection, and attach a credibility flag that travels with every exported memo format.

Agent Pushback / Data Integrity

• While coding the Methodology Agent, never make it a yes-man — it must be able to decline a user modification with explanation when methodological integrity is at stake.

Agent Service / Data Integrity

• Always architect the Methodology Agent as one callable service that runs both interactive (user negotiation) and headless (autonomous Next Move generation) modes off shared core logic.

Pattern Library / Security

• Never expose the Politogy-controlled methodological pattern library to customers; users see only generated questions, not the underlying convention library.

Ready Gate / Data Integrity

• Always block a poll from moving Draft to Ready until credibility validation passes, unless the user explicitly invokes the override mechanism.

Audit Trail / Compliance

• Always preserve the full questionnaire-negotiation audit trail (every AI draft, user request, AI response with reasoning, state transition, override) on the poll record.

IP Routing / Privacy

• Enforce the two-tier IP boundary at the data-write layer, not the UI: raw responses/segments/memos to Campaign Data, four-dimensional scores/classifications/migrations to Aggregate Intelligence, telemetry/cross-account patterns to Politogy-only.

Tier Exposure / Security

• Always gate visibility of raw four-dimensional scores by pricing tier — Free/Basic see only classifications and tags, Premium sees own-respondent scores, Enterprise gets cross-account propensity products.

Sampling Source / Data Integrity

• Never let polling run against a self-selected opt-in audience as a primary pattern — campaign polls field against the voter roll; Anonymous Web Link is an explicit edge case that writes to aggregate-only storage, never to a UVP.

Score Versioning / Data Integrity

• Always stamp every score record with the model version that produced it and persist a complete score snapshot per voter per poll; never average or recency-collapse divergent scores into a single ‘true’ value.

Analyst Claims / Compliance

• Never let the Strategic Analyst overclaim — its language for any finding must match that finding’s strength tier and clearly separate descriptive, directional, strong, and inconclusive claims.

Lane Taxonomy / Data Integrity

• Always treat message lanes as Politogy-controlled global constants from the canonical 14-lane taxonomy; never allow customers to create custom lanes (it fragments Aggregate Intelligence).

Human Launch / Compliance

• Never auto-deploy poll-derived segments or messages — a human must review and approve, and the user is always the launch authority.

Weak-Sample Flow / UX

• Always require the Fielding Scorecard to be acknowledged on-screen before strategic memo generation, and offer the three structured paths (Extend / Directional Memo / Abandon) when sample is insufficient.

Longitudinal Foundation / Data Integrity

• Always preserve Next Move chain-of-custody (source poll to Next Move to resulting poll) and flag AI-origin polls; build longitudinal data structures from day one even when surfaces are deferred to V2.

Petition

Data Ownership / Data Integrity

• Always treat every Signature Record as Politogy-owned and permanently linked to the signer’s UVP; never model it as customer-owned or deletable.

Data Exposure / Privacy

• Always keep the Aggregate Intelligence layer (circulator scores, fraud signals, propensity inputs) Politogy-internal; never expose it to any customer account.

Provenance / Data Integrity

• Always preserve full provenance (source, timestamp, confidence, chain-of-custody actor + geolocation) on every Signature Record state transition; never mutate a value without logging.

Immutability / Data Integrity

• Always store scan images and signature records as immutable from upload; never delete, overwrite, or edit a scan image.

OCR Confidence / Data Integrity

• Always flag sheets for adjudication when sheet type or any field falls below the confidence threshold; never extract or auto-accept data the AI is unsure of.

Verification Source / Data Integrity

• Always run verification against the foundational UVP master database, never against customer-tier data.

Sheet Cascade / Data Integrity

• Always cascade a sheet-level invalidation to every signature line on that sheet with full audit trail; never leave child signatures valid when their parent sheet is invalidated.

Reason Codes / Data Integrity

• Always use the global Politogy-defined reason codes for adjudication outcomes; never let accounts define ad-hoc reason codes.

Escalation / Data Integrity

• Always make Politogy escalation review binding and logged separately from customer adjudication; never let a customer override a Politogy ruling.

Portable Reputation / Data Integrity

• Always let a circulator’s quality score follow them across customer accounts; never silo reputation to a single account.

Permission Scope / Privacy

• Always scope Circulator Mobile to the circulator’s own data and assigned turf; never expose other circulators’ or campaign-wide data.

Submission Gate / Compliance

• Always block submission packet generation when sheets are in Hold or Adjudication Required, distribution is unmet, or threshold/deadline checks fail; never generate a packet past a failed validation.

Single Profile / Data Integrity

• Always treat modes as views over one UVP, writing petition signatures to the shared profile instantly; never create a duplicate voter profile or batch-sync copy.

Public Portal / Privacy

• Always keep individual signer info, circulator identities, and adjudication data out of the Public Transparency Portal; never publish PII or internal metrics.

Sub-Mode Reuse / Data Integrity

• Always reuse the shared Signature Record, Sheet, Circulator, and Petition structures across Initiative, Recall, and Candidate sub-modes; never fork separate data models per sub-mode.