Add Pol roster_excluded policy layer and API enforcement

Jack-Aaron · Jack-Aaron · commit 408aad2057c9 · 2026-05-07T22:33:42.000-05:00
Store exclusion on Pol, filter GET /api/congress roster, block celebration
and payment intent before Stripe when roster_excluded is true. Extend vest
query for payment validation without changing watcher has_stakes jobs.
diff --git a/.cursor/rules/00-index.mdc b/.cursor/rules/00-index.mdc
@@ -52,6 +52,7 @@ This directory contains comprehensive cursor rules for the POWERBACK project. Th
 - **21-election-dates.mdc** - Election dates handling, snapshots, fallbacks
 - **22-logging-telemetry.mdc** - Logging patterns, PII handling, central logger
 - **26-copy-registry.mdc** - Copy text registry patterns (referenced in specs)
+- **42-pol-roster-exclusion.mdc** - Policy exclusions from roster and new Celebrations (`roster_excluded` vs watcher `has_stakes`)
 
 ## How to Use These Rules
 
@@ -65,6 +66,7 @@ This directory contains comprehensive cursor rules for the POWERBACK project. Th
 Some rules reference others:
 - `specs/frontend-ui.md` references `28-css-property-ordering.mdc` and `29-bootstrap-css-blending.mdc`
 - `specs/escrow-and-aggregate-limits.md` references `26-copy-registry.mdc`
+- `specs/pol-roster-exclusion.md` references `42-pol-roster-exclusion.mdc`
 
 ## Rule Maintenance
 
diff --git a/.cursor/rules/05-api-patterns.mdc b/.cursor/rules/05-api-patterns.mdc
@@ -335,6 +335,11 @@ interface PaymentValidationResponse {
     message: string;
   };
 }
+
+// Roster exclusion (before Stripe): HTTP 400 body may be:
+// { code: 'POL_ROSTER_EXCLUDED', message: string } — not the shape above.
+
+// GET /api/congress roster: has_stakes true and roster_excluded not true
 ```
 
 ## Async/Await Pattern
diff --git a/.cursor/rules/12-models.mdc b/.cursor/rules/12-models.mdc
@@ -43,7 +43,7 @@ module.exports = mongoose.model('Model', ModelSchema);
 - `User.js` - User accounts and profiles
 - `Celebration.js` - Donation events
 - `Bill.js` - Congressional bills
-- `Pol.js` - Politicians and candidates
+- `Pol.js` - Politicians and candidates (includes `has_stakes` from watchers and policy `roster_excluded` / `roster_exclusion_*`; do not use `has_stakes` for policy exclusion — see `42-pol-roster-exclusion.mdc`)
 - `Applicant.js` - Users awaiting account verification
 - `ExUser.js` - Deleted users (prevent re-registration)
 - `Key.js` - API keys and credentials
diff --git a/.cursor/rules/18-ai-assistant-guidelines.mdc b/.cursor/rules/18-ai-assistant-guidelines.mdc
@@ -72,7 +72,7 @@ priority: 1
   - Cookie security and route scoping
 
 ### Documentation Updates
-- **Update relevant docs**: When changing behavior, update all relevant docs (API, HOOKS, CONTEXTS, DONATION_LIMITS, ELECTION_DATE_NOTIFICATIONS)
+- **Update relevant docs**: When changing behavior, update all relevant docs (API, HOOKS, CONTEXTS, DONATION_LIMITS, ELECTION_DATE_NOTIFICATIONS, specs e.g. pol-roster-exclusion when roster policy changes)
 - **Timing**: Update docs at the "end" of a refactor (ask user if it's the right time)
 - **Link to docs**: Keep long process/flow explanations in docs/ and link from code comments
 
diff --git a/.cursor/rules/42-pol-roster-exclusion.mdc b/.cursor/rules/42-pol-roster-exclusion.mdc
@@ -0,0 +1,41 @@
+---
+description: Pol roster exclusion policy (separate from has_stakes watcher logic)
+globs:
+  - 'models/Pol.js'
+  - 'services/congress/polRosterEligibility.js'
+  - 'controller/congress/pols.js'
+  - 'controller/congress/vest.js'
+  - 'services/celebration/orchestrationService.js'
+  - 'routes/api/payments.js'
+alwaysApply: false
+priority: 3
+---
+
+# Pol roster exclusion (policy layer)
+
+## Separation from has_stakes
+
+- `has_stakes` is computed by watcher jobs (e.g. `challengersWatcher`). Do not flip or overload it for policy exclusions (Speaker, left office, data holds, etc.).
+- Use `roster_excluded` and related fields on `Pol` for POWERBACK policy exclusions.
+
+## Pol schema (see `models/Pol.js`)
+
+- `roster_excluded` (Boolean, default false)
+- `roster_exclusion_reason` (String)
+- `roster_exclusion_category` (String; conventions listed in `ROSTER_EXCLUSION_CATEGORIES` in `services/congress/polRosterEligibility.js`)
+- `roster_exclusion_updated_at` (Date)
+
+## Enforcement
+
+- Selectable roster: `GET /api/congress` uses `controller/congress/pols.js` — query `has_stakes: true` and `roster_excluded: { $ne: true }`.
+- New celebrations: `services/celebration/orchestrationService.js` rejects excluded `pol_id` before DB write and side effects.
+- Payment intent: `routes/api/payments.js` rejects excluded `pol_id` before Stripe / `createPayment`.
+- `controller/congress/vest.js` requires both `has_stakes` and not `roster_excluded` for payment validation.
+
+## User-facing errors
+
+- HTTP 400 with `code: POL_ROSTER_EXCLUDED` and plain-language `message` from `polRosterEligibility.js`. Client surfaces via `usePaymentProcessing` rejection reasons.
+
+## Specs
+
+- `specs/pol-roster-exclusion.md`
diff --git a/docs/API.md b/docs/API.md
@@ -41,18 +41,20 @@ Each category is a link to its [`Routes`](../routes/) or relevant folder.
 - [`resolveDonation`](../controller/celebrations/resolve.js) converts a Celebration into a donation by updating the document
 - [`sendReceipt`](../controller/celebrations/receipt.js) emails Celebration receipt to user (uses refactored email system)
 - [`getWhatPolsHaveInEscrow`](../controller/celebrations/find/params/escrowed.js) sums all donation amounts for each politician from across the userbase
+- **Roster exclusion**: HTTP `400` with `code: POL_ROSTER_EXCLUDED` when `pol_id` is a `Pol` with `roster_excluded: true` — enforced in [`orchestrationService`](../services/celebration/orchestrationService.js) before create. See [`specs/pol-roster-exclusion.md`](../specs/pol-roster-exclusion.md).
 
 ### **[`Congress`](../routes/api/congress.js)**
 
-- [`getPolsByIds`](../controller/congress/methods/put/pols.js) returns a group of **Politicians** based on the ID(s) provided
-- [`getPol`](../controller/congress/methods/get/pol.js) returns a single **Politician's** document
-- [`getBill`](../controller/congress/methods/get/bill.js) returns a single **Bill's** document
+- `GET /api/congress/` — List politicians for the **selectable roster** (lobby carousel, search). [`getPols`](../controller/congress/pols.js): `has_stakes: true` and `roster_excluded` not true.
+- `GET /api/congress/members/:pol` — Single politician document ([`getPol`](../controller/congress/pol.js)); requires authentication.
+- `GET /api/congress/election-dates` — Election dates (snapshot / fallbacks).
 
 ### **[`Payments`](../routes/api/payments.js)** [(Stripe)](https://stripe.com)
 
 - [`sendPayment`](../controller/payments/createPayment.js) sends payment to [`Stripe`](https://stripe.com/docs/payments),
 - [`setupIntent`](../controller/payments/setupIntent.js) creates a "payment intent" object
 - [`setPaymentMethod`](../controller/payments/setPaymentMethod.js) creates a "payment method" i.e. user's credit card
+- **Roster exclusion**: `POST /api/payments/celebrations/:customer_id` rejects excluded `pol_id` with HTTP `400` and `code: POL_ROSTER_EXCLUDED` **before** Stripe payment intent creation (see [`polRosterEligibility`](../services/congress/polRosterEligibility.js)).
 
 > **📖 For comprehensive payment processing documentation, see [`docs/payment-processing.md`](./payment-processing.md)**  
 > **📖 For webhook processing details, see [`docs/webhooks.md`](./webhooks.md)**
@@ -85,4 +87,5 @@ Each category is a link to its [`Routes`](../routes/) or relevant folder.
 - [Webhook System](./webhooks.md) - Real-time event processing
 - [Background Jobs](./background-jobs.md) - Automated monitoring and updates
 - [Email System](./email-system.md) - Email notifications
-- [Bitcoin Donations](./bitcoin-donations.md) - Cryptocurrency support
+- [Bitcoin Donations](./bitcoin-donations.md) - Cryptocurrency support
+- [Pol roster exclusion](../specs/pol-roster-exclusion.md) - Policy exclusions for selectable roster and new Celebrations
diff --git a/docs/README.md b/docs/README.md
@@ -31,6 +31,7 @@ This directory contains comprehensive documentation for the POWERBACK.us platfor
 - **[FEC Compliance Guide](./fec-compliance-guide.md)** - Comprehensive FEC compliance requirements
 - **[Donation Limits](./donation-limits.md)** - Annual and election cycle resets
 - **[Donor Validation](./donor-validation-comprehensive.md)** - FEC "best efforts" validation system
+- **[Pol roster exclusion](../specs/pol-roster-exclusion.md)** - Policy exclusions from selectable roster and new Celebrations (vs `has_stakes` watchers)
 
 ### Celebration Lifecycle
 
diff --git a/docs/background-jobs.md b/docs/background-jobs.md
@@ -66,6 +66,7 @@ All background jobs are orchestrated through the `runWatchers` system, which:
 - Tracks challenger status changes (appeared, disappeared, reappeared)
 - Tracks incumbent dropouts
 - Updates `has_stakes` flags based on competitive race status
+- **Policy note**: POWERBACK exclusions from the selectable roster use `Pol.roster_excluded`, not watcher toggles on `has_stakes` alone. See [`specs/pol-roster-exclusion.md`](../specs/pol-roster-exclusion.md).
 - Sends email alerts to users in affected districts
 
 **Email Alerts**:
@@ -295,3 +296,4 @@ await watcher.forceWarningEmails();
 - [Election Date Notifications](./election-dates.md) - Election date change notifications
 - [Email System](./email-system.md) - Email notifications sent by watchers
 - [Status Ledger System](./status-ledger-system.md) - Celebration status tracking
+- [Pol roster exclusion](../specs/pol-roster-exclusion.md) - Roster exclusion policy vs watcher `has_stakes`
diff --git a/docs/docking-pols-runbook.md b/docs/docking-pols-runbook.md
@@ -90,4 +90,4 @@ If Senators appear in the docking collection, the Congress.gov API's `currentMem
 - `scripts/add-members-to-docking.js` -- Staging script for specific members
 - `services/utils/dockingManager.js` -- DockingManager class and CLI
 - `jobs/houseWatcher.js` -- Background job that auto-stages new members
-- `models/Pol.js` -- Pol schema definition
+- `models/Pol.js` -- Pol schema definition (`has_stakes`, policy `roster_excluded`; see [`specs/pol-roster-exclusion.md`](../specs/pol-roster-exclusion.md))
diff --git a/docs/election-dates.md b/docs/election-dates.md
@@ -196,7 +196,7 @@ The system includes robust error handling:
 
 - `User` collection with `email`, `firstName`, `compliance`, `ocd_id` fields
 - `Celebration` collection with `donatedBy`, `pol_id`, `resolved`, `defunct`, `paused` fields
-- `Pol` collection with `id`, `roles.state`, `has_stakes` fields
+- `Pol` collection with `id`, `roles.state`, `has_stakes`, and optional policy fields `roster_excluded`, `roster_exclusion_*` ([`specs/pol-roster-exclusion.md`](../specs/pol-roster-exclusion.md))
 
 ## Testing
 
diff --git a/docs/hooks.md b/docs/hooks.md
@@ -334,6 +334,8 @@ interface Handlers {
 }
 ```
 
+**Note**: Parade data ultimately comes from `GET /api/congress`, which excludes `roster_excluded` politicians (see [`specs/pol-roster-exclusion.md`](../specs/pol-roster-exclusion.md)).
+
 **Usage**:
 
 ```typescript
@@ -386,6 +388,7 @@ const [items, { setInputItems, resetSearchBar }] = useComboboxItems(
 - User data updates and navigation handling
 - PAC limit validation and error handling
 - Form submission management
+- Roster exclusion: Backend may return HTTP `400` with `code: POL_ROSTER_EXCLUDED` **before** Stripe (payment attempt) or **after** confirm when saving the celebration; both paths surface user-facing rejection reasons ([`specs/pol-roster-exclusion.md`](../specs/pol-roster-exclusion.md))
 - Comprehensive error handling for payment failures
 
 **Interface**:
@@ -425,12 +428,12 @@ interface PaymentProcessingActions {
 
 ```typescript
 const { handlePaymentSubmit } = usePaymentProcessing({
-  stripe,
-  setPaymentError,
-  setShowModal,
   setRejectedDonationReasons,
-  stopProcessingSpinner,
   startProcessingSpinner,
+  stopProcessingSpinner,
+  setPaymentError,
+  setShowModal,
+  stripe,
 });
 
 // In component
diff --git a/docs/overview.md b/docs/overview.md
@@ -129,7 +129,7 @@ The back end uses files kept in the following folders:
     - [`Bill.js`](../models/Bill.js) data describing a Bill introduced in Congress, compiled by the [Congress.GOV API](https://api.congress.gov/),
     - [`Celebration.js`](../models/Celebration.js) schema for a document storing the details of a user Celebration involving a donation amount, a political candidate recipient, etc.,
     - [`ExUser.js`](../models/ExUser.js) document outlining a user that has deleted their account to prevent signing up again with the same username,
-    - [`Pol.js`](../models/Pol.js) schema for a real politican in Congress, compiled by the [FEC API](https://api.open.fec.gov/developers/),
+    - [`Pol.js`](../models/Pol.js) schema for a real politican in Congress, compiled by the [FEC API](https://api.open.fec.gov/developers/); includes watcher-driven `has_stakes` and policy `roster_excluded` fields — see [`specs/pol-roster-exclusion.md`](../specs/pol-roster-exclusion.md),
     - [`User.js`](../models/User.js) an approved user
 
 ## Files
@@ -152,3 +152,4 @@ The back end uses files kept in the following folders:
 - [Background Jobs](./background-jobs.md) - Automated monitoring system
 - [Payment Processing](./payment-processing.md) - Stripe integration
 - [Email System](./email-system.md) - Email notifications
+- [Pol roster exclusion](../specs/pol-roster-exclusion.md) - Selectable roster and new-Celebration policy layer
diff --git a/docs/payment-processing.md b/docs/payment-processing.md
@@ -103,6 +103,7 @@ POWERBACK uses Stripe for payment processing, implementing an escrow-based syste
 ### Validation Before Payment
 
 - **Backend Validation**: FEC compliance checked before payment intent creation
+- **Roster exclusion (policy)**: Requests for a roster-excluded politician (`Pol.roster_excluded`) return HTTP **400** with `code: POL_ROSTER_EXCLUDED` and a user-facing `message` **before** any Stripe payment intent is created. Celebrations are gated the same way in `orchestrationService`. See [`specs/pol-roster-exclusion.md`](../specs/pol-roster-exclusion.md).
 - **Tier Limits**: Per-donation, annual, and per-election limits enforced
 - **PAC Limits**: Tip limits validated ($5,000 annual)
 - **Donor Validation**: Donor information validated per compliance tier
@@ -210,5 +211,6 @@ await setupIntent(req, res);
 - [Donation Limits](./donation-limits.md) - Donation limit system
 - [Webhook System](./webhooks.md) - Webhook processing
 - [API Documentation](./API.md) - Payment API endpoints
+- [Pol roster exclusion](../specs/pol-roster-exclusion.md) - Policy gate before payment and celebration create
 - [Celebration System](./defunct-celebrations-system.md) - Celebration lifecycle
 - [Client Utils](./utils.md) - Client logging and Stripe helpers (e.g. `logError` / `logWarn`, `loadStripeKey` from `@Utils`)
diff --git a/docs/social-announcements-webhooks.md b/docs/social-announcements-webhooks.md
@@ -66,7 +66,7 @@ All requests are `POST` with `Content-Type: application/json` and header `x-make
 **Celebration** (`celebration`):
 
 - `donation` – Donation amount in dollars.
-- `total_donations` – Total escrowed for this pol this election cycle (active only, has_stakes); omitted if aggregation fails.
+- `total_donations` – Total escrowed for this pol this election cycle (aggregation joins `Pol` and includes only active celebrations where linked `Pol.has_stakes`; distinct from selectable roster filtering which also applies `roster_excluded`). Omitted if aggregation fails.
 - `state`, `district`, `polName`, `handles` – Politician and district (no donor info).
 - `bill_id`, `bill_title` – Bill/condition for the celebration.
 
diff --git a/routes/api/congress.js b/routes/api/congress.js
@@ -80,15 +80,16 @@ function loadStatutoryGeneralElectionDate() {
 
 /**
  * GET /api/congress
- * Retrieves all politicians/congressional members
+ * Retrieves politicians for the selectable roster (lobby carousel / search feed)
  *
- * This endpoint returns a comprehensive list of all politicians serving in
- * the U.S. Congress, including House and Senate members. The data includes
- * biographical information, social media accounts, current party affiliation,
- * and congressional role history.
+ * The list includes only members with `has_stakes: true` who are not
+ * roster-excluded (`Pol.roster_excluded` must not be true). Full Pol
+ * documents for other flows use GET /api/congress/members/:pol (authenticated).
+ *
+ * Biographical information, social media, party, roles, etc. are sourced from
+ * OpenFEC / Congress.gov via ingestion jobs.
  *
  * The endpoint is publicly accessible and does not require authentication.
- * Data is primarily sourced from the OpenFEC API and Congress.gov API.
  *
  * @route GET /api/congress
  * @returns {Array<Object>} Array of politician objects
diff --git a/specs/SPECS.md b/specs/SPECS.md
@@ -10,6 +10,7 @@ This directory captures domain specifications that guide implementation. Each sp
 - `frontend-ui.md` - UI/UX patterns, accessibility, navigation/state, and styling (including custom hooks)
 - `jobs-notifications.md` - Background jobs, election-date updater, and email notifications
 - `pac-limit-system.md` - PAC contribution limits, tipLimitReached field, and payment flow integration
+- `pol-roster-exclusion.md` - Policy exclusions for Pol (roster + new Celebrations); separate from `has_stakes` watchers
 - `webhook-optimization.md` - Webhook processing optimization for users at PAC limits
 - `quality-assessment.md` - Quality standards, current assessment (78/100), and improvement roadmap
 - `testing-strategy.md` - Comprehensive testing approach to achieve 80%+ coverage
@@ -29,6 +30,7 @@ This directory captures domain specifications that guide implementation. Each sp
 4. Update specs/rules to reflect shipped behavior
 
 ## Quality Checks
+
 - TypeScript errors typically caught by IDE/editor during development
 - ESLint validation via `npm run lint` when needed
 - Focus on editor feedback over terminal commands for type checking
@@ -38,4 +40,3 @@ This directory captures domain specifications that guide implementation. Each sp
 - Defer to code for source of truth; specs describe intended behavior
 - Keep specs concise and actionable
 - Link concrete files/APIs where relevant
-
diff --git a/specs/backend-compliance.md b/specs/backend-compliance.md
@@ -17,6 +17,13 @@ Define server-side compliance behavior, legal limits, reset logic, and authority
 - Server is authoritative; it may block donations if validation cannot be ensured.
 - Timezone: Eastern (Washington, D.C.) for all reset calculations.
 
+## Pol roster exclusion (non-FEC policy)
+
+- **Purpose**: Block new Celebrations and remove politicians from the **selectable** roster when POWERBACK policy says they must not receive new escrowed donations (e.g. Speaker, left office, manual admin hold). This is **not** the same as `has_stakes` (watcher / competitive-race flag); do not use `has_stakes` mutations for policy exclusion.
+- **Schema**: `Pol.roster_excluded`, `roster_exclusion_reason`, `roster_exclusion_category`, `roster_exclusion_updated_at` — see `models/Pol.js` and `specs/pol-roster-exclusion.md`.
+- **Enforcement**: `GET /api/congress` roster query; `createCelebration` in `services/celebration/orchestrationService.js`; `POST /api/payments/celebrations/:customer_id` before Stripe; `controller/congress/vest.js` for payment validation path.
+- **Errors**: HTTP `400` with `code: POL_ROSTER_EXCLUDED` and user-facing `message` from `services/congress/polRosterEligibility.js`.
+
 ## Inputs / Outputs
 
 - Inputs: user donations, compliance tier, politician/state (for compliant-tier checks), current election dates snapshot, backend constants.
@@ -30,6 +37,7 @@ Define server-side compliance behavior, legal limits, reset logic, and authority
   - getElectionDates(state, electionYear?) → { primary: string|null, general: string }
 - controller/users/account/utils (promotion, compliance upgrades)
 - routes/api/payments.js (server-side validation before payment processing)
+- services/congress/polRosterEligibility.js (roster exclusion lookup and user message)
 
 ## Logic & Invariants
 
@@ -71,8 +79,8 @@ Define server-side compliance behavior, legal limits, reset logic, and authority
 ## Links
 
 - Rules: 03-backend-authority-and-compliance, 04-election-dates-policy, 09-logging-and-privacy, 40-pac-limit-system, 41-employment-status-validation
-- Code: services/electionCycleService.js, routes/api/payments.js, routes/api/celebrations.js, services/donorValidation.js
-- Related: specs/pac-limit-system.md
+- Code: services/electionCycleService.js, routes/api/payments.js, routes/api/celebrations.js, services/donorValidation.js, services/congress/polRosterEligibility.js, services/celebration/orchestrationService.js
+- Related: specs/pac-limit-system.md, specs/pol-roster-exclusion.md
 
 ## Service Architecture
 
@@ -92,6 +100,8 @@ services/
 ├── defunctCelebrationService.js   # Celebration lifecycle management
 ├── electionCycleService.js        # FEC compliance and limits
 ├── electionDateNotificationService.js # Election date change notifications
+├── congress/
+│   └── polRosterEligibility.js   # Roster exclusion policy helpers and user-facing message
 ├── fixPolName.js                  # Politician name normalization
 ├── logger.js                      # Structured logging service
 ├── promoteUser.js                 # User privilege management
diff --git a/specs/pol-roster-exclusion.md b/specs/pol-roster-exclusion.md
diff --git a/specs/project-architecture.md b/specs/project-architecture.md
