rsc-universal 0.1.1

package/skills/laravel/scripts/verify.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+#
+# verify.sh - local quality gate for a Laravel (11/12) project.
+#
+# Usage:
+#   cd <your-laravel-project-root>   # the directory containing composer.json + artisan
+#   ./verify.sh
+#
+# Runs (each only if applicable): composer validate, a framework-version sanity check,
+# Pint style in read-only --test mode, the test runner (Pest or `php artisan test`), and a
+# grep guard against `protected $guarded = []` under app/Models.
+# Read-only: never mutates source, never runs a formatter/migration in write mode.
+#
+# Degrades gracefully: if there is no Laravel project (no composer.json, or composer.json
+# without laravel/framework) or no vendor/ dir, it prints a skip notice and EXITS 0 so it
+# never blocks a non-Laravel repo. Portable to stock macOS bash 3.2.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  YELLOW=$'\033[33m'; RED=$'\033[31m'; GREEN=$'\033[32m'; RESET=$'\033[0m'
+else
+  YELLOW=''; RED=''; GREEN=''; RESET=''
+fi
+
+failed=0
+
+have() { command -v "$1" >/dev/null 2>&1; }
+warn() { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+info() { printf -- '----- %s\n' "$*"; }
+
+# Resolve a binary either as a project-local vendor/bin script or a global on PATH.
+binof() {
+  if [ -x "vendor/bin/$1" ]; then printf 'vendor/bin/%s' "$1"; return 0; fi
+  if have "$1"; then printf '%s' "$1"; return 0; fi
+  return 1
+}
+
+# --- Applicability gate: bail out cleanly when this is not a Laravel project. ---
+if [ ! -f composer.json ]; then
+  warn "no composer.json in $(pwd) - not a Laravel project, nothing to verify."
+  exit 0
+fi
+if ! grep -q 'laravel/framework' composer.json 2>/dev/null; then
+  warn "composer.json has no laravel/framework dependency - skipping Laravel checks."
+  exit 0
+fi
+if [ ! -d vendor ]; then
+  warn "no vendor/ dir - run 'composer install' first. Skipping (exit 0)."
+  exit 0
+fi
+
+# 1. composer validate - the manifest must be well-formed.
+info "composer validate"
+if have composer; then
+  if composer validate --strict --no-check-publish >/dev/null 2>&1; then
+    ok "composer.json valid"
+  elif composer validate --no-check-publish >/dev/null 2>&1; then
+    warn "composer.json valid but not strict-clean (lock drift / metadata) - run: composer validate --strict"
+  else
+    fail "composer validate reported errors (run: composer validate)"
+  fi
+else
+  warn "composer not found (https://getcomposer.org)"
+fi
+
+# 2. Framework version sanity. Prefer artisan; fall back to composer.lock.
+info "framework version"
+if [ -f artisan ] && have php; then
+  ver="$(php artisan --version 2>/dev/null || true)"
+  if [ -n "$ver" ]; then ok "$ver"; else warn "could not read 'php artisan --version'"; fi
+elif [ -f composer.lock ]; then
+  lver="$(grep -A2 '"name": "laravel/framework"' composer.lock 2>/dev/null | grep '"version"' | head -n1 || true)"
+  if [ -n "$lver" ]; then ok "composer.lock laravel/framework:$lver"; else warn "version not found in composer.lock"; fi
+else
+  warn "no artisan / composer.lock - cannot determine framework version"
+fi
+
+# 3. Mass-assignment guard: flag `protected $guarded = []` under app/Models.
+info "mass-assignment guard (no \$guarded = [])"
+if [ -d app/Models ]; then
+  # Match an empty-array $guarded with any inner whitespace; ignore commented lines best-effort.
+  if grep -REn 'protected[[:space:]]+\$guarded[[:space:]]*=[[:space:]]*\[[[:space:]]*\]' app/Models 2>/dev/null \
+       | grep -v '^[^:]*:[0-9]*:[[:space:]]*//' >/dev/null; then
+    grep -REn 'protected[[:space:]]+\$guarded[[:space:]]*=[[:space:]]*\[[[:space:]]*\]' app/Models 2>/dev/null \
+      | grep -v '^[^:]*:[0-9]*:[[:space:]]*//' || true
+    fail "found 'protected \$guarded = []' (mass-assignment footgun) - use an explicit \$fillable allowlist"
+  else
+    ok "no open \$guarded found in app/Models"
+  fi
+else
+  warn "no app/Models dir - skipping mass-assignment guard"
+fi
+
+# 4. Style: Pint in read-only --test mode (never fixes).
+info "style (Pint)"
+if pint_bin="$(binof pint)"; then
+  if $pint_bin --test >/dev/null 2>&1; then
+    ok "pint clean"
+  else
+    fail "pint reports style issues (run: $pint_bin)"
+  fi
+else
+  warn "no pint binary (composer require --dev laravel/pint) - skipping style"
+fi
+
+# 5. Tests: Pest preferred, else `php artisan test`.
+info "tests (Pest / artisan test)"
+if [ -f phpunit.xml ] || [ -f phpunit.xml.dist ] || [ -d tests ]; then
+  if pest_bin="$(binof pest)"; then
+    if $pest_bin >/dev/null 2>&1; then ok "pest green"; else fail "pest failed (run: $pest_bin)"; fi
+  elif [ -f artisan ] && have php; then
+    if php artisan test >/dev/null 2>&1; then ok "artisan test green"; else fail "artisan test failed (run: php artisan test)"; fi
+  else
+    warn "tests present but no runner found (composer require --dev pestphp/pest)"
+  fi
+else
+  warn "no phpunit.xml / tests dir - skipping tests"
+fi
+
+echo
+if [ "$failed" -ne 0 ]; then
+  printf '%sFAIL:%s one or more checks failed.\n' "$RED" "$RESET"
+  exit 1
+fi
+printf '%sPASS:%s all checks passed.\n' "$GREEN" "$RESET"

package/skills/lead-gen/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: lead-gen
+description: "Use when you need to find and qualify prospects, build a target list, or score and prioritize leads before anyone reaches out — defining an ICP, sourcing named accounts/contacts from Apollo/ZoomInfo/Clay, deduping against the CRM, and ranking with a fit+intent+engagement model. Triggers: 'build me a prospect list', 'who should we sell to', 'score these leads', 'which accounts do we call first', 'tighten our ICP', 'is this cold list GDPR-safe', 'necesito una lista de clientes potenciales', 'califica estos leads', 'a qui truquem primer'. NOT writing or sending the outreach (that is cold-outreach), NOT tracking the deal after first contact (that is sales-pipeline)."
+tags: [lead-generation, prospecting, icp, lead-scoring, sales]
+recommends: [cold-outreach, sales-pipeline, market-research, data-scraper, spreadsheet-ops, email-deliverability, gdpr-privacy]
+origin: risco
+---
+
+# Lead Gen — The List and the Model That Ranks It
+
+*You turn "we sell X to Y" into a deduplicated, scored, compliance-cleared roster of named accounts and people. You define the target, you build the list, you rank it — then you stop. You do not write the email and you do not run the deal.*
+
+The identity of this skill is **the list and its scoring model**, not the messages sent to it and not the pipeline it becomes. Everything you produce is a *prioritized roster + the rationale that ranked it*. The hand-off is the finish line, not the campaign.
+
+## The pipeline — three phases, two gates
+
+Run these in order. Each gate is a hard stop: do not advance until the prior phase produced its artifact.
+
+1. **Define the target** → a falsifiable ICP + persona. *Why: you cannot dedupe or score against a vibe; a vague ICP guarantees reps chase the wrong companies.*
+2. **Build the list** → sourced, deduped, verified rows with provenance. *Why: an unverified or undocumented list is a deliverability and legal liability before a single email goes out.*
+3. **Score & prioritize** → tiered list (A/B/C) with subscores + handoff packet. *Why: an unsorted list means reps work the easy-to-reach names, not the right ones.*
+
+Between phase 2 and the handoff sits the **compliance gate** (GDPR LIA + CAN-SPAM). Run it *before* you hand anything off, never after the first send.
+
+## Phase 1 — Define a falsifiable ICP
+
+An ICP is falsifiable when you can look at any company and answer "in or out?" with no judgement call. Write three blocks:
+
+- **Firmographic** — headcount band, revenue band, region/country, industry/NAICS, funding stage. Numbers, not adjectives.
+- **Technographic / intent** — required stack (e.g. "runs Salesforce"), or an active trigger (hiring for role X, recently raised, surging on a topic). Apollo filters on 1,500+ technologies and active job postings, so make these checkable. *(docs.apollo.io People API Search, accessed 2026-06-02.)*
+- **Negative criteria** — the `disqualify if…` list. This is the half everyone skips and the half that saves the most rep time.
+
+Then write the **buyer persona(s)** inside the account: title, seniority, the pain they own, the trigger that makes now the moment.
+
+```text
+BAD ICP (un-falsifiable — every company "kind of" fits):
+  "Mid-market SaaS companies that could use better analytics."
+
+GOOD ICP (any company resolves to in/out):
+  Firmographic:   50–500 employees · $5M–$50M ARR · US + EU · B2B SaaS
+  Technographic:  runs Snowflake OR BigQuery · hiring a "Data Analyst" now
+  Negative:       DISQUALIFY IF <50 employees · agency/reseller · no data team
+  Persona:        Head of Data / VP Eng · owns dashboard sprawl · triggered by
+                  a recent funding round (new headcount to equip)
+```
+
+## Decision — pick the qualification framework by deal size
+
+Do not default to BANT. The framework must match the deal's size and cycle, or you qualify on the wrong signals. *(leadsatscale.com / callingagency.com qualification guides, accessed 2026-06-02.)*
+
+| Framework | Stands for | Use when |
+|---|---|---|
+| **BANT** | Budget · Authority · Need · Timeline | High-velocity SMB, deals under ~$50K ARR, short cycle, 1–2 stakeholders |
+| **CHAMP** | Challenges · Authority · Money · Prioritization | Consultative selling — lead with the prospect's problem, not your budget question |
+| **MEDDIC** | Metrics · Economic-buyer · Decision-criteria · Decision-process · Identify-pain · Champion | Enterprise, deals over ~$100K, 5+ stakeholders, long cycle |
+
+The framework you pick becomes the qualification fields on every row — so choose it before you score, not after.
+
+## Phase 2 — Build the list
+
+**Source selection.** No single database wins, so the 2025 norm is a *waterfall*: layer providers and stop at the first verified hit. *(starnus.com / cleanlist.ai provider comparisons, accessed 2026-06-02.)*
+
+| Provider | Rough coverage | Note |
+|---|---|---|
+| Apollo | ~200M contacts | Search is free + credit-free; enrichment costs credits; ~78% email accuracy |
+| ZoomInfo | 321M+ contacts / 104M+ companies | ~84% email accuracy; strongest firmographics |
+| People Data Labs | Broad person/company graph | Good as a waterfall fill layer |
+| Clay | Orchestrates 100+ sources | The waterfall *engine* — runs the layering for you |
+
+**The waterfall rule:** order providers by accuracy-per-dollar, query the next layer only for rows the previous one missed or could not verify, and **stop at the first verified hit**. You pay once per contact, not once per provider.
+
+**Apollo People Search → Enrichment flow.** Search and enrichment are two different endpoints — search finds people but returns *no* emails/phones; enrichment (credit-consuming) returns the contact data. *(docs.apollo.io, accessed 2026-06-02.)*
+
+```text
+1. POST /api/v1/mixed_people/api_search   (free, no credits)
+   filters: person_titles, person_seniorities, organization_locations,
+            organization_num_employees_ranges, q_organization_keyword_tags,
+            currently_using_any_of_technology_uids, q_organization_job_titles
+   → returns up to 50,000 records (100/page × 500 pages) — IDs + firmographics,
+     NO email/phone.
+
+2. POST /api/v1/people/bulk_match     (consumes credits)
+   → enriches the IDs you actually want with email + phone.
+```
+
+Search broad and free first, then spend credits enriching only the rows that survive your ICP filter and dedupe.
+
+**Dedupe against the CRM.** Before enriching, strip rows that already exist in the CRM (match on company domain + person email/LinkedIn). You do not pay to re-source a known account, and you do not want a rep cold-touching an active opportunity.
+
+**Verify — mandatory, not optional.** Apollo (~78%) and ZoomInfo (~84%) email accuracy both sit at the edge of the high-volume-sender red-flag line. *(cleanlist.ai / fundraiseinsider.com, accessed 2026-06-02.)* Run a verification pass (bounce-check the address) before any row is handed off — a stale list is a `lead-gen` defect, not a copy or deliverability problem.
+
+Full provider comparison, the waterfall ordering heuristic, and the provenance/compliance field spec each row must carry → `references/data-sources.md`.
+
+## Phase 3 — Score & prioritize
+
+Use a composite **100-point** model. Single-signal scoring fails; the proven split is **~30 fit + ~50 engagement + ~20 intent**. *(houseofmartech.com / theinsightcollective.com intent-scoring guides, accessed 2026-06-02.)*
+
+- **Fit (≈30)** — how well the account matches the ICP firmographics/technographics.
+- **Engagement (≈50)** — behavioral signals: site visits, content downloads, replies, demo views.
+- **Intent (≈20)** — third-party intent surge on your category/keywords.
+
+**The load-bearing rule: intent without fit is noise.** A 10-person company surging on "enterprise CRM" is not your buyer — fit gates the score. Never let an intent spike alone tier a row up.
+
+Tier on the total:
+
+| Tier | Score | SLA |
+|---|---|---|
+| A | 90–100 | Route now, first contact within 24h |
+| B | 75–89 | 48h SLA |
+| C | 60–74 | Nurture, no rep time yet |
+
+The full 100-pt rubric, negative scoring, score decay, the tier→SLA map, and the scored-list **CSV schema** → `references/scoring-model.md`.
+
+**Handoff packet** (what leaves this skill): the tiered CSV, the ICP + persona it was built against, per-row provenance, and the scoring rationale for the A tier. Nothing more — no message, no pipeline stage.
+
+## Compliance gate — run BEFORE handoff
+
+A list that ships without these fields is not done. Run both checklists; the strictest applicable jurisdiction wins.
+
+**GDPR (EU B2B).** Cold B2B email runs on **legitimate interest, Art. 6(1)(f) — not consent** — but only if you have done the paperwork. *(derrick-app.com / instantly.ai GDPR-B2B guides, accessed 2026-06-02.)*
+
+- [ ] A documented **Legitimate Interest Assessment (LIA)** exists.
+- [ ] Every email will carry the data-source disclosure + a privacy-policy link + a one-click opt-out.
+- [ ] Objections will be honored.
+- [ ] **No purchased or scraped data** — those confer no lawful basis, full stop.
+
+**CAN-SPAM (US).** *(ftc.gov CAN-SPAM compliance guide, accessed 2026-06-02.)*
+
+- [ ] A valid physical postal address is available for the footer.
+- [ ] A clear opt-out mechanism, honored within **10 business days**, live ≥30 days.
+- [ ] Penalty awareness: up to **$53,088 per violating email**, FTC-enforced.
+
+To lint a produced list file for the required columns, score-range sanity, provenance presence, and a compliance flag, run `scripts/verify.sh path/to/list.csv` (read-only).
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Buying/scraping a list and emailing it | No GDPR lawful basis; CAN-SPAM exposure up to $53,088/email | Source + verify + document the LIA + provenance per row |
+| Scoring on intent alone | Intent without fit is noise — surge ≠ buyer | Composite fit+intent+engagement; fit gates the tier |
+| One ICP/framework for every deal size | BANT on a MEDDIC deal qualifies on the wrong signals | Pick the framework by deal size/cycle first |
+| Skipping email verification | 78–84% accuracy = bounces + domain reputation damage | Waterfall + a verify pass before handoff |
+| Enriching before deduping against the CRM | You pay to re-source known accounts and risk touching live deals | Dedupe on domain/email first, enrich the survivors |
+| Handing reps a raw, unsorted list | Reps work easy-to-reach names, not the right ones | Tier A/B/C with SLAs and an A-tier rationale |
+| Treating the list as the goal | A list is not a pipeline and not a campaign | Hand A/B to cold-outreach, accepted leads to sales-pipeline |
+
+## Handoff — where the list goes next
+
+This skill stops at a scored, compliance-cleared list. From there:
+
+- The **A/B tiers + persona context** go to `../cold-outreach/SKILL.md` — that skill writes the message and the cadence; you do not.
+- **Accepted leads** (worked and responsive) go to `../sales-pipeline/SKILL.md` — that skill tracks stages, forecasts, and manages the deal; you do not.
+- If the request is really "how big is this market / which segment?" with no named list, that is `../market-research/SKILL.md`, not this skill.
+
+When the deliverable would be a message, a pipeline stage, or a market sizing — route. Your job ended at the ranked roster.

package/skills/lead-gen/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — lead-gen
+
+`cases.yaml` is run by the repo's skill-eval harness. The `should_trigger` and `should_not_trigger` prompts test routing: each prompt is matched against this skill's description+triggers, and the near-miss cases assert the router prefers the named sibling (`route_to`) instead of `lead-gen` — that is how we catch the skill grabbing work that belongs to `cold-outreach`, `sales-pipeline`, `market-research`, `data-scraper`, or `email-deliverability`. The `capability` case is graded (manually or by an LLM judge) against its `must_include` rubric: feed the scenario, then check the produced list actually carries a falsifiable ICP, summed fit/intent/engagement subscores, A/B/C tiers matching the bands, per-row provenance, a compliance note, and an explicit handoff. Run it with the harness from the repo root; there is no standalone runner in this folder.

package/skills/lead-gen/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: lead-gen
+
+should_trigger:
+  - prompt: "Build me a list of 200 mid-market fintech CTOs in the EU we could sell to."
+    why: "Core list-building — named accounts/contacts against an ICP."
+  - prompt: "We have 500 inbound signups; which ones do we call first?"
+    why: "Prioritization is lead scoring — non-obvious because it reads like CRM/ops, but the deliverable is a tiered, ranked list."
+  - prompt: "Help me tighten our ICP, our reps keep chasing the wrong companies."
+    why: "ICP definition is phase 1 of this skill."
+  - prompt: "Is this cold prospect list legal to email under GDPR before we send?"
+    why: "The compliance gate (GDPR LIA, no scraped basis) is part of making a list ship-ready — non-obvious that lead-gen owns it, not a generic legal skill."
+  - prompt: "Necesito una lista de clientes potenciales para nuestro SaaS de logística."
+    why: "Spanish core trigger — build a target list of prospects."
+  - prompt: "A qui de la nostra base truquem primer, tenim 300 comptes sense prioritzar?"
+    why: "Catalan trigger — scoring/tiering an unprioritized account list."
+
+should_not_trigger:
+  - prompt: "Write the cold email sequence for these prospects."
+    route_to: cold-outreach
+    why: "Writing the message and cadence is cold-outreach; lead-gen stops at the scored list."
+  - prompt: "Move this lead to 'negotiation' and update the forecast."
+    route_to: sales-pipeline
+    why: "Tracking a lead through stages and forecasting is sales-pipeline, after first contact."
+  - prompt: "How big is the EU logistics-SaaS market and what segments exist?"
+    route_to: market-research
+    why: "Market sizing/segmentation with no named list is market-research."
+  - prompt: "Build a scraper to pull every company from this directory site."
+    route_to: data-scraper
+    why: "Building the extraction tool is data-scraper; lead-gen consumes sourced data, it does not build scrapers."
+  - prompt: "Set up SPF/DKIM and warm up our domain before we email the list."
+    route_to: email-deliverability
+    why: "DNS/auth and warm-up are email-deliverability, upstream of sending."
+
+capability:
+  - scenario: "Given an ICP and a raw 50-row enrichment export, produce a scored, tiered, compliance-cleared handoff list."
+    must_include:
+      - "A falsifiable ICP with at least one negative/disqualify criterion."
+      - "A composite score with fit/intent/engagement subscores summing to a 0–100 total."
+      - "A/B/C tiering tied to the score bands (A 90–100, B 75–89, C 60–74) with SLAs."
+      - "A per-row data-source/provenance field."
+      - "The 'intent without fit is noise' rule applied (low-fit rows not tiered A on intent)."
+      - "A compliance note (GDPR lawful basis OR CAN-SPAM opt-out/address) before handoff."
+      - "An explicit handoff statement to cold-outreach (A/B tiers) and sales-pipeline (accepted leads)."

package/skills/lead-gen/references/data-sources.md

@@ -0,0 +1,87 @@
+# Reference — data sources, the Apollo API flow, and the provenance spec
+
+How to pick providers, run the waterfall, call Apollo's search→enrichment flow, and what every row must carry to stay legal.
+
+## Provider comparison
+
+No single database wins — coverage and accuracy vary by region and segment, which is why waterfall enrichment is the 2025 norm. *(starnus.com / cleanlist.ai / fundraiseinsider.com comparisons, accessed 2026-06-02.)*
+
+| Provider | Coverage | Email accuracy | Best for |
+|---|---|---|---|
+| Apollo | ~200M contacts | ~78% | Free/credit-free search; broad SMB + mid-market |
+| ZoomInfo | 321M+ contacts / 104M+ companies | ~84% | Strongest firmographics; enterprise |
+| People Data Labs | Broad person/company graph | Varies | Programmatic fill layer in a waterfall |
+| Clay | Orchestrates 100+ sources | Inherits the layer that hit | The waterfall engine itself |
+
+Both Apollo (~78%) and ZoomInfo (~84%) sit at the edge of the high-volume-sender red-flag line, so a verification pass is mandatory regardless of provider.
+
+## Waterfall ordering heuristic
+
+1. Order providers by **accuracy-per-dollar** for your segment (often ZoomInfo for firmographics, Apollo for free volume, PDL/others as fill).
+2. Query the cheapest broad layer first (Apollo free search) to get the candidate set.
+3. For each row still missing a verified email, query the next layer — **only for the misses**.
+4. **Stop at the first verified hit.** You pay once per contact, not once per provider.
+5. Drop rows no layer can verify rather than ship them unverified.
+
+Clay can run steps 2–4 for you across 100+ sources; the heuristic is the same whether you orchestrate it by hand or let Clay do it.
+
+## Apollo People Search → Enrichment flow
+
+Search and enrichment are two separate endpoints. Search **does not consume credits** and is capped at **50,000 records per query** (100/page × 500 pages), but returns **no emails or phones**. Contact data comes only from the (credit-consuming) enrichment endpoints. *(docs.apollo.io/reference/people-api-search, accessed 2026-06-02.)*
+
+```http
+# Step 1 — search (free, no credits): find people, get IDs + firmographics
+POST https://api.apollo.io/api/v1/mixed_people/api_search
+Content-Type: application/json
+X-Api-Key: <key>
+
+{
+  "person_titles": ["VP Engineering", "Head of Data"],
+  "person_seniorities": ["vp", "head"],
+  "organization_locations": ["United States", "European Union"],
+  "organization_num_employees_ranges": ["51,200", "201,500"],
+  "currently_using_any_of_technology_uids": ["snowflake", "bigquery"],
+  "q_organization_job_titles": ["Data Analyst"],
+  "page": 1,
+  "per_page": 100
+}
+# → up to 50,000 records across 500 pages; NO email/phone in the response.
+```
+
+```http
+# Step 2 — enrich (consumes credits): get email + phone for the chosen IDs
+POST https://api.apollo.io/api/v1/people/bulk_match
+Content-Type: application/json
+X-Api-Key: <key>
+
+{ "details": [ { "id": "<person_id_from_search>" }, ... ],
+  "reveal_personal_emails": false }
+# → enriches only the rows you pass — dedupe + ICP-filter BEFORE this call so you
+#   never spend credits on rows you would have dropped.
+```
+
+Available search filters include title, seniority, location, headcount, revenue, 1,500+ technologies, and active job postings — make your ICP technographic/intent criteria map onto these so they are machine-checkable.
+
+## Dedupe against the CRM (before enriching)
+
+Match candidate rows against existing CRM records on **company domain + person email/LinkedIn URL**. Drop:
+
+- Accounts that are already open opportunities (do not cold-touch a live deal).
+- Contacts already owned by a rep.
+- Current customers, partners, and competitors.
+
+Deduping before enrichment saves credits and prevents the cardinal sin of a rep cold-emailing an active account.
+
+## Provenance / compliance field spec (every row carries this)
+
+A list with no provenance has no defensible lawful basis under GDPR, and purchased/scraped data confers none. *(derrick-app.com / instantly.ai GDPR-B2B guides, accessed 2026-06-02.)* Each row must carry:
+
+| Field | Why it must exist |
+|---|---|
+| `source` | Provider + acquisition date — the data-source disclosure GDPR requires you surface to the contact |
+| `acquired_at` | Date the row was sourced — feeds score decay and freshness checks |
+| `verified` | Did the verification pass confirm the email? Unverified rows do not ship |
+| `opt_out` | Compliance flag proving the email will carry a one-click opt-out + source disclosure |
+| `lawful_basis` | The Art. 6(1)(f) legitimate-interest reference (the LIA exists) for EU contacts |
+
+These collapse into the scored-list CSV's `source` and `opt_out` columns that `scripts/verify.sh` checks; keep the fuller fields in your working file and project the required columns into the handoff CSV.

package/skills/lead-gen/references/scoring-model.md

@@ -0,0 +1,93 @@
+# Reference — the composite scoring model + scored-list schema
+
+The full 100-point rubric the SKILL summarizes, plus the CSV schema that `scripts/verify.sh` lints.
+
+## The 100-point split
+
+Single-signal scoring fails; layer three signal families. *(houseofmartech.com / theinsightcollective.com intent-scoring guides, accessed 2026-06-02.)*
+
+| Family | Weight | What it measures |
+|---|---|---|
+| Fit | ~30 | Match to the ICP firmographics/technographics |
+| Engagement | ~50 | Observed behavior (the strongest predictor) |
+| Intent | ~20 | Third-party surge on your category |
+
+### Fit (0–30) — example allocation
+
+| Signal | Points |
+|---|---|
+| Headcount in ICP band | 8 |
+| Revenue/funding in ICP band | 6 |
+| Region/country in target | 4 |
+| Industry/vertical match | 6 |
+| Required tech in stack | 6 |
+
+### Engagement (0–50) — example allocation
+
+| Signal | Points |
+|---|---|
+| Replied to a prior touch | 18 |
+| Booked/attended a demo or event | 14 |
+| Repeat site visits (pricing/product pages) | 10 |
+| Content download / form fill | 8 |
+
+### Intent (0–20) — example allocation
+
+| Signal | Points |
+|---|---|
+| Third-party intent surge on your category | 12 |
+| Active job posting matching the trigger | 5 |
+| Recent funding/expansion event | 3 |
+
+## Negative scoring (subtract, do not skip)
+
+Negative signals keep junk out of the A tier. Apply after the positive total.
+
+| Signal | Points |
+|---|---|
+| Matches a `disqualify if…` ICP rule | −100 (force to bottom / drop) |
+| Competitor, current customer, or partner | −100 |
+| Personal/free-mail domain only (no business email) | −15 |
+| Headcount below the floor | −20 |
+
+## Score decay
+
+Engagement and intent are time-sensitive. Decay them so a 6-month-old signal does not inflate a cold account:
+
+- Engagement/intent signals older than **30 days** → multiply that family's contribution by 0.5.
+- Older than **90 days** → contribution = 0 (the signal is stale, re-source the trigger).
+- Fit does not decay (firmographics are stable).
+
+## The "intent without fit is noise" gate
+
+Apply this hard rule before tiering: **if Fit < 15 (half of max), cap the total at 74 (tier C) regardless of intent/engagement.** A 10-person company surging on "enterprise CRM" must not reach the A tier on intent alone.
+
+## Tier → SLA map
+
+| Tier | Total | Action | SLA |
+|---|---|---|---|
+| A | 90–100 | Route to a rep now | First contact within 24h |
+| B | 75–89 | Queue for outreach | Within 48h |
+| C | 60–74 | Nurture only | No rep time; revisit on new signal |
+| (below 60) | <60 | Suppress | Not handed off |
+
+## Scored-list CSV schema (the artifact verify.sh checks)
+
+Every produced list must carry exactly these columns. Header row is required.
+
+```csv
+account,contact,source,fit,intent,engagement,total,tier,opt_out
+Acme Corp,Dana Lee <dana@acme.com>,apollo:bulk_match 2026-06-02,26,14,46,86,B,source-disclosed
+Globex,Sam Ortiz <sam@globex.io>,zoominfo 2026-06-01,29,18,48,95,A,source-disclosed
+```
+
+Column rules `verify.sh` enforces:
+
+- `account`, `contact` — non-empty.
+- `source` — non-empty provenance string (provider + date, or the export origin).
+- `fit`, `intent`, `engagement` — integers ≥ 0; their sum equals `total`.
+- `total` — integer 0–100.
+- `tier` — `A` (90–100), `B` (75–89), `C` (60–74); the label must match the band.
+- `opt_out` — non-empty compliance flag (e.g. `source-disclosed`, `opt-out-ready`); proves the compliance gate ran.
+
+A list missing any of these columns, or with a tier that does not match its score band, or with an empty provenance/compliance cell, is not shippable.