State file: Prospecting & Leads/enrichment_rotation_state.json
Plan & monthly budget (CURRENT — upgraded 2026-04-25):
- BeenVerified Premium ($89.99/mo, 400 reports/month)
- Daily target: 12 (HOT 3, WARM 3, NURTURE 2, SWITCH 3, LOW 1) → ~360/mo, leaves 40-report buffer
- Soft stop: 380 consumed → finish current lead, exit cleanly
- Hard stop: 395 consumed → abort BEFORE next View click
- Monthly counter at
monthly_budget.consumed_this_month. Reset to 0 on month rollover (comparecurrent_monthto today'sYYYY-MM). - Increment counter only on successful View click + page hydration. NO_MATCH (no View click) does NOT count. SoS lookups do NOT count. Hydration retries on the same View click do NOT count (the credit was spent on the click).
- Persist counter to state every 5 leads + at end-of-run.
State structure:
tiers.{TIER}.queue— lead_ids in rotation ordertiers.{TIER}.cursor— 0-based next indextiers.{TIER}.per_day_target— HOT/WARM/SWITCH=3, NURTURE=2, LOW=1enrichment_history[lead_id]—{last_enriched, email_found, phone_found, runs}monthly_budget—{monthly_cap:400, daily_target:12, current_month, consumed_this_month, buffer:40, soft_stop_at:380, hard_stop_at:395}retry_queue— drained at start of each run (Step 1a)blocker_state—active:falseafter the 2026-04-25 upgrade resolution
Workflow:
1. Step 0 (NEW) — Monthly budget guard: reset counter on month rollover; if hard-stop hit → write heartbeat skipped and exit; if today_target would breach buffer → reduce per-tier picks (drop LOW first, then NURTURE, SWITCH, WARM; preserve ≥1 HOT and ≥1 WARM).
2. Drain retry_queue first (Step 1a) — each retry that hits BV consumes 1 report.
3. Pick today_target leads from tier cursors (default 12).
4. Run BV (Step 5) — increment counter on each successful View+hydrate.
5. Persist state including counter.
LLC/Trust branch: If owner_name contains LLC|TRUST|INC|CORP|LP|PARTNERS|HOLDINGS|PROPERTIES|ESTATE OF, run mandatory inline VT/CO Secretary of State lookup BEFORE BeenVerified — do not defer. SoS lookups do not consume BV credits.
Owner name parser:
LASTNAME, FIRST MIDDLE & CO-OWNER→ fname=FIRST, lname=LASTNAMESMITH JOHN A & SMITH JANE B→ fname=JOHN, lname=SMITH
Required browser tabs: HubSpot (https://app.hubspot.com/contacts/23273108/...) + BeenVerified. If BV session expired, pause and report — never enter credentials.
Status (2026-04-25): ✅ Premium upgrade live. 12-lead/day cadence active. 8-lead retry queue from prior outage will drain first; expect ~10-12 BV reports consumed per run depending on NO_MATCH rate.
How to apply: Before running or debugging, read the state file first. Verify monthly_budget.consumed_this_month is sensible (matches sum of recent daily reports' monthly_budget.consumed_at_end - consumed_at_start). If counter has drifted from reality, recompute from Daily Enrichment Logs/ for the month and reset.
Skill at ~/Documents/Claude/Scheduled/daily-beenverified-enrichment/SKILL.md (canonical) and ~/.claude/scheduled-tasks/daily-beenverified-enrichment/SKILL.md (scheduled wrapper).