@vruum/skills 0.6.40 → 0.6.42

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vruum",
-  "version": "0.6.40",
+  "version": "0.6.42",
   "description": "Vruum AI skills + remote MCP server for B2B GTM teams. Slash commands for outreach triage, engagement triage, pipeline filling, prospect enrichment, and reply diagnosis, paired with the full Vruum MCP tool surface over OAuth 2.1.",
   "author": {
     "name": "Vruum AI",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vruum",
-  "version": "0.6.40",
+  "version": "0.6.42",
   "description": "Vruum AI skills + remote MCP server for B2B GTM teams. Skills for outreach triage, engagement triage, pipeline filling, prospect enrichment, and reply diagnosis, paired with the full Vruum MCP tool surface over OAuth 2.1.",
   "author": {
     "name": "Vruum AI",

package/README.md

@@ -86,7 +86,7 @@ the public skill instead of leaving a broken link.
 - `/expansion-fill` — Source expansion-ready customers for outreach. Finds closed-won customers >60 days old with no open follow-on deal and surfaces them for an expansion play. Use when: expand customer, find upsell opportunities, NRR play, expansion opportunities, customers ripe for expansion, who can we expand to.
 - `/ingest-meetings` — Pull meeting transcripts from your connected Google Drive into Vruum. Attaches each transcript to the right person and deal as a meeting on their timeline, and turns its action items into tasks that surface in your daily briefing. You review every attach before anything is written; safe to re-run. Use when: ingest meetings, import meeting notes, pull transcripts, log my meetings, action items from meetings, Gemini notes, Read.ai transcripts, turn meetings into tasks.
 - `/outreach-triage` — Review and approve your pending outreach drafts across LinkedIn and email. Use when: triage, review queue, morning review, check messages, approve outreach, what needs review.
-- `/pipeline-fill` — Source-agnostic pipeline orchestrator. Picks a source per campaign (Sales Nav / YC / CSV / discovery), runs harness deep research, applies a pre-filter gate, then saves into the campaign via the backend authoritative match_score>=70 gate. Use when: fill pipeline, import prospects, daily imports, need more prospects, discover prospects from scratch, deep research before import.
+- `/pipeline-fill` — Source-agnostic pipeline orchestrator. Picks a source per campaign (Sales Nav / YC / CSV / account list / discovery), runs harness deep research, applies a pre-filter gate, then saves into the campaign via the backend authoritative match_score>=70 gate. Use when: fill pipeline, import prospects, daily imports, need more prospects, discover prospects from scratch, find buyers at these companies, deep research before import.
 - `/sales-nav-deep-fill` — Sales Nav harness source for /pipeline-fill. Pre-filters Sales Nav profiles via vruum-pipeline-filter, produces a candidate list, hands off to /pipeline-fill for deep research and import. Use when: sales nav with deep research, sales nav harness mode, in-chat sales nav.
 - `/vruum-guide` — Guide to running Vruum from your own AI harness. First run: guided onboarding from empty account to first reviewed outreach draft. After: reads live account state, recommends the single next most valuable action, hands off to the right skill. Use when: get started, onboarding, how do I use vruum, what should I do next, where do I start.
 - `/vruum-skills-upgrade` — Upgrade @vruum/skills to the latest npm version and re-sync ~/.vruum/. Use when: upgrade vruum skills, update vruum, pull latest vruum skills, or when the preamble reports UPGRADE_AVAILABLE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vruum/skills",
-  "version": "0.6.40",
+  "version": "0.6.42",
   "description": "Vruum AI skills for Claude Code, Claude Desktop, Codex CLI, and any AI assistant with a skill directory. Slash commands for outreach triage, engagement triage, pipeline filling, prospect enrichment, and reply diagnosis. Pairs with the Vruum MCP server at https://api.vruum.ai/mcp.",
   "license": "MIT",
   "repository": {
@@ -42,5 +42,5 @@
     "outreach",
     "gtm"
   ],
-  "contentHash": "2d1d42147392e5fc34a8eb81caa215c216163d5d7ac85c15557be06d115776f4"
+  "contentHash": "116c4499218d3234185bf864ba4b84c1233ee375f967f9c66c4a34b97d325294"
 }

package/skills/csv-pipeline-fill/SKILL.md

@@ -47,6 +47,8 @@ If `name` is mapped, defer the first/last split to the engine doc's Step 7 (cano
 
 ### Step 4: Resolve ambiguous mappings
 
+**Company-only CSV → route to the `account_list` source.** If `company` maps but no person-identity column does (no `name`/first+last, no `linkedin_url`, no `email`), this is an account list, not a contact list. Don't ask the operator to force a mapping — hand the company column to `/pipeline-fill`'s `account-list` source, whose committee-resolution step resolves `buyers_per_account` ICP-matching buyers per company. Say so in one line: "No contact columns — treating this as an account list ({N} companies); /pipeline-fill will resolve the buying committee."
+
 If any required field can't be auto-mapped (`name`/(first+last) AND `company`, OR `linkedin_url`), show the operator the detected headers + sample row and ask which column maps to which field. Don't guess silently — silent guessing is the source of "why did my CSV import 50 prospects with the wrong company" bugs.
 
 For multi-column ambiguity (e.g. two columns matching `email`), pick the leftmost match and note it in the operator output.
@@ -113,6 +115,7 @@ Continue automatically? (y/n)
 - **Duplicate rows** — in-CSV dedup before handoff.
 - **LinkedIn URLs with tracking params** — query string stripped during canonicalization.
 - **Mixed name format** (some rows have full_name, others have first/last) — engine handles both via Step 7's identity-resolution flow.
+- **Company-only CSV** (no contact columns) — routed to `/pipeline-fill`'s `account-list` source at Step 4; never imported as contacts.
 - **Empty CSV** — orchestrator says "CSV has no data rows after dedup; nothing to research" and exits.
 
 ## Notes

package/skills/pipeline-fill/RESEARCH-ENGINE.md

@@ -30,6 +30,7 @@ All harness source skills produce candidate lists matching this shape exactly. T
 
 **Rules:**
 - At minimum, each candidate needs **either** `linkedin_url` **or** (`name`-fields + `company`). Candidates with neither are skipped at Step 3.
+- **A company-only row (name/domain but no person) is not a valid candidate.** Sources holding companies must run the shared **Committee resolution** step in `SKILL.md` (companies → people, capped at `buyers_per_account`) before handing off to this engine. Do not improvise buyer selection out of company-research prose — that reintroduces marquee-name skew and an undocumented depth of 1 per account.
 - `full_name` is a convenience for sources that don't pre-split. Engine's Step 7 splits via last-space heuristic (`Jane van der Merwe` → first=`Jane`, last=`van der Merwe`). Multi-token surnames like `Maria Del Carmen Garcia` may split imperfectly — Phase B's linkedin_fetch call (`research` action=linkedin_fetch) returns canonical first/last when `linkedin_url` is present and overrides the heuristic.
 - Field additions are additive only. Removing a field is a breaking change for source skills.
 - `source_policy`, candidate examples, and progress events have executable schemas under `contracts/`. Validate handoffs against them before provider calls.
@@ -59,7 +60,12 @@ Stable operator-visible codes:
 | `linkedin_auth_required` | LinkedIn account is disconnected/expired | reconnect LinkedIn |
 | `company_identity_conflict` | exact evidence points to different companies | correct the evidence; never auto-merge |
 | `company_resolution_failed` | company resolver returned no canonical row | retry once, then inspect resolver logs and evidence |
-| `company_research_save_failed` | company research persistence failed with unknown commit status | inspect stored rows before any replay |
+| `company_research_commit_unknown` | company research persistence response was lost | replay only the identical payload with the same idempotency key |
+| `company_research_serialization_conflict` | bounded transaction retries were exhausted | replay only the identical payload with the same idempotency key |
+| `idempotency_key_reused` | a save key was reused with different content | keep the original payload or generate a new key |
+| `company_research_invalid_value` | a company anchor or research value is malformed | correct the named value before retrying |
+| `company_research_source_invalid` | a shared field lacks admissible evidence | add/correct sources_by_field before retrying |
+| `company_research_save_failed` | save failed outside the atomic receipt boundary | inspect the correlation ID before deciding whether to retry |
 | `person_not_visible` | supplied person is outside the caller's tenant | use a tenant-visible person or omit `person_id` |
 | `person_not_found_for_update` | save_person anchors matched no one in your pipeline (update-only) | search and pass `payload.person_id`, or use save_discovered's `person` block for a new prospect |
 | `identity_unverifiable` | person has neither a LinkedIn URL nor an email | include `person.linkedin_url` or `person.email` |
@@ -97,9 +103,11 @@ Per campaign's candidate list:
 
 1. **MCP precheck + ICP load** (above) — abort run on failure.
 2. **Batch dedup against existing pipeline.** Call `search(type="people", query=[{name, company, linkedin_url} for each candidate])`. Returns one match record per candidate (in input order). Drop candidates with non-null `match` — they're already in pipeline.
-3. **Batch company-cache check.** Collect unique company domains from surviving candidates. Call `fetch(type="company_research", id=[the domains])`. Returns `[{domain, cached_research, age_days}]`.
-   - Cache hit (`cached_research != null` AND `age_days <= 90`) → company skips Phase A; the cached research carries forward.
-   - Cache miss or stale (`age_days > 90`) → company joins the Phase A research queue.
+3. **Batch company fixed-field reuse check.** Collect unique company domains from surviving candidates. Call `fetch(type="company_research", id=[the domains], filters={"requested_fields":["company_summary","company_stage","current_priorities","funding_data","growth_metrics"]})`.
+   - Reuse only values whose field entry has `status="reusable"`.
+   - `core_reuse.reusable` means the shared summary core is reusable; it never means the campaign brief is complete.
+   - Missing, unsourced, stale, invalid, and absent fields remain null inputs. Never carry a raw stored value forward.
+   - **Every company still runs Phase A** for campaign-relative outbound motion, ACV class, sales-cycle inference, and triggers. Reusable fixed values are inputs that avoid redundant fetching, not a Phase A skip signal.
 4. **Operator confirmation gate (CSV / large lists only).** If the original candidate list was >200 (CSV) or >100 (manual list), confirm count to process before continuing.
 
 **Latency:** ~2s for batch dedup + ~1s for batch company cache, regardless of list size. (Per-prospect iteration was ~12s for 60 prospects pre-batch primitives.)
@@ -110,7 +118,7 @@ Per campaign's candidate list:
 
 **Concurrency cap: 10 parallel.** Phase A subagents don't call `research` with action=linkedin_fetch — they hit `fetch` (type=company_research), `research` (action=enrich_company), `WebFetch`, `WebSearch`. No Unipile rate-limit pressure.
 
-Dispatch one `vruum-company-deep-researcher` per unique uncached company. Subagent file at `.claude/agents/vruum-company-deep-researcher.md` defines the workflow + tools.
+Dispatch one `vruum-company-deep-researcher` per unique company. Subagent file at `.claude/agents/vruum-company-deep-researcher.md` defines the workflow + tools. Include the reusable fixed-field values and their evidence in the prompt; the researcher must still compute campaign-relative outputs.
 
 Dispatch prompt template (fill in placeholders):
 
@@ -125,7 +133,7 @@ acv_floor: {dollars or default $10K}
 Run your workflow (a–i) and return the structured output block.
 ```
 
-Each subagent returns: `company_name`, `domain`, `funding_data`, `growth_metrics`, `current_priorities`, `outbound_motion_score` (0/1/2), `acv_class` (smb/mid/ent), `sales_cycle_inference` (short/medium/long), `triggers[]`, `STATUS: ok | failed`, `CACHE_HIT`. Subagents never persist; the orchestrator resolves `company_id` in Step 7 when the requested mode permits writes.
+Each subagent returns: `company_name`, `domain`, `company_summary`, `company_stage`, `funding_data`, `growth_metrics`, `current_priorities`, `sources_by_field` (`{field:[{url,title?,observed_at}]}`), `outbound_motion_score` (0/1/2), `acv_class` (smb/mid/ent), `sales_cycle_inference` (short/medium/long), `triggers[]`, `STATUS: ok | failed`, and the list of reused fixed fields. Subagents never persist; the orchestrator resolves `company_id` in Step 7 when the requested mode permits writes.
 
 **Wait for the wave to complete before Phase B.** Phase B inputs depend on Phase A's signals (or null if failed).
 
@@ -145,7 +153,7 @@ Helps operators distinguish "still working" from "stuck."
 
 **Malformed LinkedIn fallback:** if the selected candidate already has a Vruum `person_id` and LinkedIn returns an invalid/malformed-profile result, preserve that `person_id` and retry the enrichment once through the first allowed structured provider in `source_policy` (Clay when selected/connected). Pass the same `person_id` in the PAYLOAD to `research(action="save_person", payload={person_id: ..., ...})` — update-only; never as the facade `id` argument. This is a provider fallback for one identity, not a new-person discovery. Never fall back on LinkedIn 429/rate-limit responses or timeouts; surface those for a later retry. If the fallback's email or LinkedIn URL belongs to another person, the backend returns `person_identity_conflict`; stop and surface it rather than dropping `person_id` and creating a duplicate.
 
-Dispatch one `vruum-prospect-deep-researcher` per surviving candidate. Subagent file at `.claude/agents/vruum-prospect-deep-researcher.md`.
+Dispatch one `vruum-prospect-deep-researcher` per surviving candidate. Subagent file at `.claude/agents/vruum-prospect-deep-researcher.md`. The fan-out is strictly 1:1 with the surviving candidate list — depth per account is decided upstream by `buyers_per_account` in the committee-resolution step, never by Phase B adding or trimming people per company.
 
 Dispatch prompt template:
 
@@ -226,7 +234,7 @@ Apply the requested mode before any persistence:
 Per surviving prospect:
 
 ### a. Save company research (once per company)
-If the prospect's company isn't already cached and Phase A produced fresh research, call `research(action="save_company", payload={name: <Phase A COMPANY>, website: <Phase A DOMAIN or canonical URL>, funding_data, growth_metrics, current_priorities: <newline-joined descriptions + source URLs>})`. The API field is `name`, not `company_name`; it accepts `website`, not `domain`; and `current_priorities` is one string, so serialize the Phase A object list instead of passing the list through. Skip if `CACHE_HIT: true` for that company.
+When Phase A produced any newly researched fixed fields, call `research(action="save_company", payload={idempotency_key: <stable run/company save key>, name: <Phase A COMPANY>, website: <Phase A DOMAIN or canonical URL>, company_summary, company_stage, funding_data, growth_metrics, current_priorities: <newline-joined descriptions>, sources_by_field})`. The API field is `name`, not `company_name`; it accepts `website`, not `domain`; and `current_priorities` is one string. Omit reusable fields that were not revalidated so the atomic patch preserves them. Explicit null deliberately clears a field, so do not send null merely because Phase A did not research it. `sources_by_field` keys must equal exactly the supplied non-null research fields. Preserve the identical idempotency key and payload for unknown-commit replay; every bulk item needs its own key.
 
 ### b. Identity prep (names + company linkage for the atomic save)
 
@@ -347,9 +355,13 @@ Pipeline fill complete: {campaign_name} (source: {source}, mode: {harness|platfo
 Candidates flow:
   source       : {N from source skill output}
   pre-flight   : {after dedup, after company-cache hit}
-  phase A      : {company subagents fired} ({cached_skip} skipped via cache)
+  phase A      : {company subagents fired} (0 skipped via cache; fixed fields reused: {count})
   phase B      : {prospect subagents fired} ({linkedin_unavailable} dismissed)
 
+For runs that went through committee resolution (account_list, discovery Path B), also report:
+  accounts unresolved : {N}  (list the companies + providers tried — from the committee-resolution hand-off)
+and group the per-prospect outcomes by `raw_signals.source_company` so the operator reads results per account.
+
 Harness pre-filter gate:
   pass         : {N}
   warming      : {N}

package/skills/pipeline-fill/SKILL.md

@@ -2,25 +2,27 @@
 name: pipeline-fill
 description: >-
   Source-agnostic pipeline orchestrator. Picks a source per campaign (Sales Nav
-  / YC / CSV / discovery), runs harness deep research, applies a pre-filter
-  gate, then saves into the campaign via the backend authoritative
+  / YC / CSV / account list / discovery), runs harness deep research, applies a
+  pre-filter gate, then saves into the campaign via the backend authoritative
   match_score>=70 gate. Use when: fill pipeline, import prospects, daily
-  imports, need more prospects, discover prospects from scratch, deep research
-  before import.
+  imports, need more prospects, discover prospects from scratch, find buyers at
+  these companies, deep research before import.
 ---
 # Pipeline Fill
 
-You are a source-agnostic pipeline filler. You pick campaigns to fill, pick a source per campaign (Sales Nav / YC / CSV / discovery), and orchestrate harness deep research that gates against the campaign ICP before saving prospects into the backend pipeline.
+You are a source-agnostic pipeline filler. You pick campaigns to fill, pick a source per campaign (Sales Nav / YC / CSV / account list / discovery), and orchestrate harness deep research that gates against the campaign ICP before saving prospects into the backend pipeline.
 
 ## Why this skill exists
 
-Filling your pipeline by source-of-the-day is normal. Sales Nav drying up doesn't mean you're stuck — pick YC, paste a CSV, or run discovery (paste candidates OR describe an ICP and the harness sources them via WebSearch + Vruum MCP + LinkedIn search). This skill orchestrates deep research per prospect in your IDE (your compute), scores against campaign ICP, then lets the backend enforce the fixed `match_score >= 70` gate.
+Filling your pipeline by source-of-the-day is normal. Sales Nav drying up doesn't mean you're stuck — pick YC, paste a CSV, hand over a list of target accounts (the harness resolves the buying committee per account), or run discovery (paste candidates OR describe an ICP and the harness sources them via WebSearch + Vruum MCP + LinkedIn search). This skill orchestrates deep research per prospect in your IDE (your compute), scores against campaign ICP, then lets the backend enforce the fixed `match_score >= 70` gate.
 
 ## Where the heavy logic lives
 
 Steps 3–8 (pre-flight, Phase A research, Phase B research, harness gate, save chain, audit-log report) are defined in `RESEARCH-ENGINE.md` (in this same skill directory). This skill owns:
 - Step 1: campaign picker (with ETA)
 - Step 2: source picker (conditional PLATFORM block + always-visible HARNESS block)
+- The committee-resolution shared step (companies → people; used by every company-producing source)
+- The account-list handler (company names/domains in, candidate list out)
 - The discovery-mode handler (paste candidates inline OR describe an ICP and source via harness tools)
 - The multi-campaign grammar
 
@@ -53,6 +55,7 @@ The orchestrator's MCP precheck at the top of Step 3 (the `fetch` type=research_
 - `prospect_list` (optional): pre-built candidate list matching the canonical shape in `RESEARCH-ENGINE.md`. If provided, skip the source-picker step and go straight to Step 3 (pre-flight). This is how source skills hand off.
 - `source_policy` (optional): machine-readable provider policy matching `contracts/source-policy.schema.json`. It owns `selected_source`, `source_mode`, `prohibited_sources`, ordered `allowed_fallbacks`, bounded wave sizes, and transient retry attempts. Treat prohibited providers as unavailable: do not call status/list/search endpoints for them.
 - `campaign(s)`: target campaign(s); multi-campaign supported.
+- `buyers_per_account` (optional): how many buying-committee members to resolve per company when the source produces companies rather than people. Range 1–5. Per-source defaults: `discovery` → 2 (the surface is unqualified — optimize for reach, spread across more accounts), `account_list` → 3 (the account is already qualified — optimize for depth on the committee). Precedence: explicit operator value > a target stated in the campaign description (e.g. "~2 per account") > the per-source default. Sources that produce people directly (Sales Nav, YC, contact CSVs, discovery Path A) ignore this input.
 - `mode`: `research-only` | `save` | `save-and-enroll` (default: `save-and-enroll`).
 
 ## Workflow — Step 1: Show pipeline status & pick campaigns
@@ -82,13 +85,23 @@ ETA estimates: ~2s for batch Step 3 dedup + ~30s/wave Phase A + ~60s/wave Phase
 - Mark campaigns already at target with ✓ and don't number them
 - Show per-campaign ETA so operator can budget time
 
-**Wait for the user's response.** Parse: "all", "1, 3", "skip 2", "just the CFO ones", etc. Only proceed with the selected campaigns.
+**Buyers-per-account line (company-producing sources only).** When the source is already known to produce companies at Step 1 — the operator handed an account list, or named discovery with an ICP brief — append one line under the table so depth is an explicit decision, never a silent default:
+
+```
+Buyers per account: 3 (account-list default; range 1–5 — reply "buyers N" to change)
+```
+
+If the source isn't known yet at Step 1 (the common "fill my pipeline" path), defer this line to source-resolution time — the account-list handler and discovery Path B each confirm it before resolving. Wherever it renders, resolve the shown number via the `buyers_per_account` precedence in Inputs (explicit value > campaign-description target > per-source default), and name which rule produced it (e.g. "2 — campaign description says '~2 per account'").
+
+**Wait for the user's response.** Parse: "all", "1, 3", "skip 2", "just the CFO ones", "buyers 3", etc. Only proceed with the selected campaigns.
 
 ## Workflow — Step 2: Pick source per campaign (only if `prospect_list` not provided)
 
 **Default to `discovery`.** Unless the operator named a source (in their prompt or a prior turn), don't lead with the picker — default to the `discovery` source (the describe-an-ICP path: source against the campaign's own ICP via WebSearch + Vruum MCP + LinkedIn search) and announce it in one line so it stays overridable, e.g.:
 
-> Sourcing {campaign_name} via discovery (ICP-based, long-tail). Reply `sales-nav`, `yc`, `csv`, or `picker` to switch.
+> Sourcing {campaign_name} via discovery (ICP-based, long-tail). Reply `sales-nav`, `yc`, `csv`, `account-list`, or `picker` to switch.
+
+**Account-list auto-detect:** if the operator's input is a list of company names or domains with no person identities (no personal names, no `/in/` LinkedIn URLs, no emails — e.g. pasted company lines, or a spreadsheet whose only mappable column is `company`), that is the `account_list` source. Announce it ("Reading this as an account list — {N} companies; I'll resolve the buying committee per account") instead of defaulting to discovery or misreading the rows as contacts.
 
 CSV and Sales Nav are fully supported when selected. `source_policy` is a per-run routing contract: an explicit "use CSV" or "use Sales Nav" selects that capability; an explicit "no CSV" or "no Sales Nav" prohibits it only for this run. Never persist a seller's personal source preference as a tenant-wide capability restriction.
 
@@ -96,7 +109,7 @@ Why discovery is the default: keyword/Sales-Nav sources keep returning the same
 
 Per selected campaign, when the operator wants to choose the source explicitly, prompt:
 
-In **public mode** (the package builder strips the PLATFORM block from this skill before publishing), the picker shows only HARNESS modes, renumbered 1–4:
+In **public mode** (the package builder strips the PLATFORM block from this skill before publishing), the picker shows only HARNESS modes, renumbered 1–5:
 
 ```
 Source for {campaign_name}?
@@ -104,10 +117,11 @@ Source for {campaign_name}?
     1. sales-nav-deep    — Sales Nav profiles + harness deep research
     2. yc                — scrape YC directory with filters you provide
     3. csv               — read a CSV file (path next), harness deep research
-    4. discovery         — paste candidates inline OR describe an ICP and I'll source them via WebSearch + Vruum MCP + LinkedIn search
+    4. account-list      — paste company names/domains (or a company-only CSV); I resolve the buying committee per account
+    5. discovery         — paste candidates inline OR describe an ICP and I'll source them via WebSearch + Vruum MCP + LinkedIn search
 ```
 
-The conditional rendering happens at package-build time, not at skill-runtime — when the orchestrator runs in operator mode it sees the 6-option block; when it runs in public mode (stripped package) it sees only the 4-option block. Source-skill dispatch logic below uses option labels (`sales-nav-platform`, `yc`, etc.), not numbers, so the renumbering is cosmetic.
+The conditional rendering happens at package-build time, not at skill-runtime — when the orchestrator runs in operator mode it sees the 7-option block; when it runs in public mode (stripped package) it sees only the 5-option block. Source-skill dispatch logic below uses option labels (`sales-nav-platform`, `yc`, etc.), not numbers, so the renumbering is cosmetic.
 
 Per source pick, dispatch:
 
@@ -115,11 +129,42 @@ Per source pick, dispatch:
 - `csv-platform` → invoke `/csv-platform-fill` (calls `import_prospects` action=csv_start; backend handles everything; same — skip Steps 3-8).
 - `sales-nav-deep` → invoke `/sales-nav-deep-fill` to produce a candidate list, then continue to Step 3 with it.
 - `yc` → invoke `/yc-pipeline-fill` to produce a candidate list, then continue to Step 3 with it.
-- `csv` → invoke `/csv-pipeline-fill` to produce a candidate list, then continue to Step 3 with it.
+- `csv` → invoke `/csv-pipeline-fill` to produce a candidate list, then continue to Step 3 with it. (A company-only CSV — no contact columns — routes to `account-list` instead; `/csv-pipeline-fill` documents the same redirect.)
+- `account-list` → use the account-list handler below (parse companies → committee resolution → candidate list), then continue to Step 3 with it.
 - `discovery` → use the discovery-mode handler below to produce a candidate list (handler branches: paste-shaped input → parse, prose ICP brief → harness sources via WebSearch + Vruum MCP + LinkedIn search), then continue to Step 3 with it.
 
 **Multi-campaign behavior:** campaigns run sequentially. Campaign 1's Step 7 (save chain + bulk enroll) completes before campaign 2's Step 3 starts. Predictable rate-limit behavior, simple progress narrative. Trade-off: 3-campaign fills are ~37min wall-clock vs ~22min if Phase A/B were overlapped across campaigns. Cross-campaign overlap is a v2.
 
+## Committee resolution (shared step: companies → people)
+
+The canonical candidate shape in `RESEARCH-ENGINE.md` is person-shaped — a company-only row is invalid by construction. This step is the single route from companies to people. **Every source that ends up holding companies runs it** (`account_list` always; `discovery` Path B after sourcing companies; a company-only CSV redirected from `/csv-pipeline-fill`). Sources that produce people directly skip it, and YC is a deliberate exemption: it is founder-first by design — the founder *is* the buyer, so `/yc-pipeline-fill` keeps its own founder extraction. Never improvise around this step by hand-picking a buyer out of research prose — see the anti-skew rule below.
+
+**Contract:**
+- **Input:** a list of companies, each with `company_name` and/or `domain` (at least one), plus the campaign's ICP target titles/seniority and a resolved `buyers_per_account` (see Inputs).
+- **Output:** the canonical person-shaped candidate list defined in `RESEARCH-ENGINE.md`, ready for Step 3. Set `raw_signals.source_company` so the report can group by account.
+
+**Per company:**
+1. Pull up to `buyers_per_account` people matching the campaign's ICP titles/seniority, using the first available provider in this order (same order as discovery sourcing; apply `source_policy` before any call):
+   - **Structured B2B provider** — e.g. Clay `find-and-enrich-contacts-at-company` with the title/seniority filter.
+   - **LinkedIn / Sales Nav** people-at-known-company via `import_prospects action=sales_nav_search` — fine here because the company is fixed; the marquee-name skew applies to company discovery, not to enumerating a known committee. Mind LinkedIn quota.
+   - **Email finder** — Hunter via `search type=companies {domain, seniority}`.
+   - **Web** — `WebSearch` for "{company} {title}" + team/about pages; the universal fallback.
+2. **Select by title fit, not visibility.** When the provider returns more than `buyers_per_account` matches, rank by ICP title/seniority fit — never by follower count, press coverage, or how often the name appears in research prose. The buyer with no public profile is often the one actually running the function; picking the famous name per account is the same marquee-name skew this skill warns about for Sales Nav.
+3. **Companies that resolve to zero people** are reported by this step at hand-off ("no ICP-matching contacts found at {company} via {providers tried}") and counted in the engine's Step 8 report (`accounts unresolved`), never silently dropped. They cannot enter the engine (the candidate shape is person-shaped), so the hand-off summary is where the gap surfaces.
+
+Provider calls run in the standard bounded waves (company-level actions ≤10, person/LinkedIn actions ≤5) with progress objects per `contracts/run-progress.schema.json`, using `phase: "committee_resolution"`.
+
+## Account-list handler (for `account-list` source)
+
+Input is company names or domains — pasted lines, or a company-only CSV/xlsx redirected from `/csv-pipeline-fill`. This is a thin wrapper around the shared committee-resolution step:
+
+1. **Parse companies.** One company per line (or per row). A line that looks like a domain (`acme.com`) sets `domain`; otherwise it's `company_name`. Drop blanks and `#` comments; dedupe case-insensitively. Above 100 accounts, confirm: "{N} accounts — process all, or first M? (a/N)".
+2. **Anchor on campaign ICP.** Read the campaign's ICP (via `fetch` type=campaign and `fetch` type=settings subtype=profile) to get target titles/seniority. Show a one-line synthesis and the resolved `buyers_per_account` — full precedence per Inputs: an explicit operator value wins, else a campaign-description target like "~2 per account", else this source's default of 3 (the accounts are already qualified, go deeper) — and confirm before resolving.
+3. **Run committee resolution** (shared step above) across the account list.
+4. **Show the resolved list** grouped by account — `Company → Name (title) [source]` — and get a "go" / "drop X" before continuing to Step 3.
+
+The territory/fit gate on the *companies* themselves still happens in Phase A + the harness gate — the handler doesn't pre-judge accounts, it only turns them into people.
+
 ## Discovery-mode handler (for `discovery` source)
 
 Discovery mode covers two paths off the same prompt:
@@ -147,7 +192,7 @@ Operator gives a brief like "Series A-C SaaS founders, US, 50-500 ppl" or "direc
 
    Apply `source_policy` before inventorying or calling providers. Validate the entire object against `contracts/source-policy.schema.json` before the first provider call. If `selected_source` is disconnected, stop with code `source_unavailable`; exclusive mode never substitutes, while preferred mode may use only the first connected entry in `allowed_fallbacks`. Announce the resolved policy in one line ("Sourcing via Clay — firmographic pull + committee enrichment; web as allowed backup; Sales Nav prohibited") so the operator can redirect.
 3. **Source companies first, by firmographics — aim past the obvious names** — use the chosen tool to pull companies matching the merged ICP by stage / headcount / vertical / geo, NOT by marquee-name lookup (the saturated set IS the famous names). With a data provider, run the firmographic query directly; with web only, work funding announcements + directories.
-4. **Resolve the buying committee per company** — for each candidate company, pull ICP-matching titles via the same provider's contact enrichment (e.g. Clay `find-and-enrich-contacts-at-company`) or `search type=companies {domain, seniority}` (Hunter). Cap ~5 people/company to spread the surface.
+4. **Resolve the buying committee per company** — run the shared **Committee resolution** step above on the sourced companies, with `buyers_per_account` resolved per Inputs (discovery default 2 — the surface is unqualified, so spread it across more accounts rather than going deep on any one).
 5. **Dedup against existing pipeline** — for each discovered person, check `search` type=people with a name/company keyword query so you don't research someone the campaign already has. This is where saturated names drop out, cheaply, before any research spend.
 6. **Show the discovered list to the operator** before handoff. Format: `Name (title) — Company [source] [linkedin]`. Cap the surface at 2x daily_target so we don't over-source. Get a "go" / "drop X" before continuing.
 

package/skills/pipeline-fill/contracts/examples.json

@@ -32,6 +32,24 @@
       "person_wave_size": 5,
       "transient_retry_attempts": 2,
       "reason": "Use only Clay; stop if it is unavailable."
+    },
+    "account_list_committee_depth": {
+      "version": "1",
+      "selected_source": "clay",
+      "source_mode": "preferred",
+      "prohibited_sources": [
+        "sales_nav",
+        "linkedin"
+      ],
+      "allowed_fallbacks": [
+        "hunter",
+        "web"
+      ],
+      "company_wave_size": 10,
+      "person_wave_size": 5,
+      "transient_retry_attempts": 2,
+      "buyers_per_account": 3,
+      "reason": "Operator-supplied account list; resolve a 3-person buying committee per account without touching LinkedIn quota."
     }
   },
   "progress": {
@@ -52,6 +70,23 @@
       "elapsed_seconds": 34,
       "eta_seconds": 0
     },
+    "committee_wave": {
+      "version": "1",
+      "state": "running",
+      "phase": "committee_resolution",
+      "provider": "clay",
+      "wave": 1,
+      "wave_count": 3,
+      "completed": 5,
+      "total": 15,
+      "failed": 0,
+      "not_attempted": 10,
+      "safe_retry_items": [],
+      "ambiguous_items": [],
+      "code": null,
+      "elapsed_seconds": 21,
+      "eta_seconds": 42
+    },
     "person_wave": {
       "version": "1",
       "state": "partial",

package/skills/pipeline-fill/contracts/run-progress.schema.json

@@ -34,6 +34,7 @@
     "phase": {
       "enum": [
         "company_research",
+        "committee_resolution",
         "person_research",
         "assignment"
       ]

package/skills/pipeline-fill/contracts/source-policy.schema.json

@@ -72,6 +72,12 @@
       "maximum": 2,
       "default": 2
     },
+    "buyers_per_account": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 5,
+      "description": "Buying-committee members to resolve per company in the shared committee-resolution step. No schema-level default on purpose: the default is per-source (discovery 2, account_list 3) and resolved by the orchestrator; a campaign-description target overrides the per-source default, an explicit operator value overrides both."
+    },
     "reason": {
       "type": "string",
       "minLength": 1
@@ -79,6 +85,7 @@
   },
   "$defs": {
     "provider": {
+      "$comment": "account_list is deliberately absent: it is operator-supplied input, not a callable provider. Committee resolution for an account list runs through the providers listed here under this same policy.",
       "enum": [
         "clay",
         "sales_nav",