@vruum/skills 0.6.35 → 0.6.37

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vruum",
-  "version": "0.6.35",
+  "version": "0.6.37",
   "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.35",
+  "version": "0.6.37",
   "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

@@ -63,6 +63,14 @@ Download and upload via **Settings → Customize → Plugins → "+"**.
 npx @vruum/skills install --target /path/to/skills/dir
 ```
 
+## Coexisting with operator skills
+
+The public and operator skill bundles can coexist in the same harness. For
+overlapping skill names, a valid operator-owned installation takes precedence.
+Public installs and uninstalls preserve the operator bundle's links and update
+checker. If an operator link becomes stale, the next public install restores
+the public skill instead of leaving a broken link.
+
 ## Skills
 
 <!-- generated:skills-begin -->

package/install.js

@@ -37,6 +37,7 @@ const VRUUM_ROOT = path.join(os.homedir(), '.vruum');
 const VRUUM_SKILLS = path.join(VRUUM_ROOT, 'skills');
 const VRUUM_AGENTS = path.join(VRUUM_ROOT, 'agents');
 const VRUUM_BIN = path.join(VRUUM_ROOT, 'bin');
+const VRUUM_OPERATOR_ROOT = path.join(VRUUM_ROOT, 'skills-operator');
 const VRUUM_VERSION_FILE = path.join(VRUUM_ROOT, 'VERSION');
 const PKG_BIN = path.join(PACKAGE_ROOT, 'bin');
 
@@ -154,7 +155,7 @@ function syncVruumRoot({ dryRun }) {
       `would sync ${PKG_SKILLS} -> ${VRUUM_SKILLS} (with auto-update prelude)`,
     ];
     if (fs.existsSync(PKG_AGENTS)) rows.push(`would sync ${PKG_AGENTS} -> ${VRUUM_AGENTS}`);
-    if (fs.existsSync(PKG_BIN)) rows.push(`would sync ${PKG_BIN} -> ${VRUUM_BIN}`);
+    if (fs.existsSync(PKG_BIN)) rows.push(`would merge ${PKG_BIN} -> ${VRUUM_BIN}`);
     rows.push(`would write ${VRUUM_VERSION_FILE} = ${VERSION}`);
     return rows;
   }
@@ -174,14 +175,18 @@ function syncVruumRoot({ dryRun }) {
     rows.push(`synced ${VRUUM_AGENTS}`);
   }
 
-  // Bin scripts — update-check needs to land at a stable path and be exec.
+  // Bin scripts share ~/.vruum/bin with the operator installer. Copy only this
+  // package's files; replacing the directory would delete the operator update
+  // checker and make that bundle permanently stale.
   if (fs.existsSync(PKG_BIN)) {
-    fs.rmSync(VRUUM_BIN, { recursive: true, force: true });
-    fs.cpSync(PKG_BIN, VRUUM_BIN, { recursive: true });
-    for (const entry of fs.readdirSync(VRUUM_BIN)) {
-      fs.chmodSync(path.join(VRUUM_BIN, entry), 0o755);
+    fs.mkdirSync(VRUUM_BIN, { recursive: true });
+    for (const entry of fs.readdirSync(PKG_BIN)) {
+      const src = path.join(PKG_BIN, entry);
+      const dst = path.join(VRUUM_BIN, entry);
+      fs.cpSync(src, dst, { recursive: true, force: true });
+      fs.chmodSync(dst, 0o755);
     }
-    rows.push(`synced ${VRUUM_BIN}`);
+    rows.push(`merged ${PKG_BIN} -> ${VRUUM_BIN}`);
   }
 
   // VERSION file — read by vruum-skills-update-check as the local version.
@@ -205,6 +210,25 @@ function isOurLink(dst, linkTarget) {
   return resolved === VRUUM_SKILLS || resolved.startsWith(VRUUM_SKILLS + path.sep);
 }
 
+// Operator skills are a strict superset with multi-company scoping. When both
+// installers are present, operator links win for overlapping names regardless
+// of install order. Public-only names still link normally.
+function isOperatorLink(dst, linkTarget) {
+  const resolved = path.isAbsolute(linkTarget)
+    ? path.resolve(linkTarget)
+    : path.resolve(path.dirname(dst), linkTarget);
+  return resolved === VRUUM_OPERATOR_ROOT
+    || resolved.startsWith(VRUUM_OPERATOR_ROOT + path.sep);
+}
+
+function hasSkillFile(dir) {
+  try {
+    return fs.statSync(path.join(dir, 'SKILL.md')).isFile();
+  } catch {
+    return false;
+  }
+}
+
 // Prune pass — after relinking current skills, remove links for skills no
 // longer in the package (renamed or deleted), but ONLY symlinks this installer
 // owns (target under ~/.vruum/skills/). Non-symlinks (real user dirs/files) and
@@ -276,6 +300,22 @@ function linkSkill({ name, srcAbs, target, dryRun }) {
   if (existing?.kind === 'symlink' && existing.target === srcAbs) {
     return { name, target, action: 'already-linked' };
   }
+  const resolvedExistingTarget = existing?.kind === 'symlink'
+    ? (path.isAbsolute(existing.target)
+      ? path.resolve(existing.target)
+      : path.resolve(path.dirname(dst), existing.target))
+    : null;
+  const operatorSkillIsUsable = resolvedExistingTarget
+    && isOperatorLink(dst, existing.target)
+    && hasSkillFile(resolvedExistingTarget);
+  if (operatorSkillIsUsable) {
+    return {
+      name,
+      target,
+      action: 'operator-kept',
+      reason: 'operator bundle takes precedence for overlapping skills',
+    };
+  }
   if (existing && existing.kind !== 'symlink') {
     return {
       name,
@@ -441,7 +481,7 @@ function commandUninstall({ targets: extraTargets, dryRun }) {
   // Only clean up our own subdirectories — ~/.vruum/ is a shared state dir
   // (e.g. the .agents/ vruum-update-check keeps config.yaml + snooze state
   // there, and both installers share that config).
-  for (const dir of [VRUUM_SKILLS, VRUUM_AGENTS, VRUUM_BIN]) {
+  for (const dir of [VRUUM_SKILLS, VRUUM_AGENTS]) {
     if (!fs.existsSync(dir)) continue;
     if (dryRun) {
       console.log(`${prefix}would remove ${dir}`);
@@ -450,6 +490,23 @@ function commandUninstall({ targets: extraTargets, dryRun }) {
       console.log(`${prefix}removed ${dir}`);
     }
   }
+  // Remove only binaries shipped by the public package. The operator update
+  // checker in the same directory belongs to the operator installer.
+  if (fs.existsSync(PKG_BIN) && fs.existsSync(VRUUM_BIN)) {
+    for (const entry of fs.readdirSync(PKG_BIN)) {
+      const dst = path.join(VRUUM_BIN, entry);
+      if (!fs.existsSync(dst)) continue;
+      if (dryRun) {
+        console.log(`${prefix}would remove ${dst}`);
+      } else {
+        fs.rmSync(dst, { recursive: true, force: true });
+        console.log(`${prefix}removed ${dst}`);
+      }
+    }
+    if (!dryRun && fs.readdirSync(VRUUM_BIN).length === 0) {
+      fs.rmdirSync(VRUUM_BIN);
+    }
+  }
   if (fs.existsSync(VRUUM_VERSION_FILE)) {
     if (dryRun) {
       console.log(`${prefix}would remove ${VRUUM_VERSION_FILE}`);
@@ -543,6 +600,7 @@ module.exports = {
   listAvailableSkills,
   linkSkill,
   isOurLink,
+  isOperatorLink,
   pruneStaleLinks,
   pruneLegacyCodexLinks,
   commandInstall,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vruum/skills",
-  "version": "0.6.35",
+  "version": "0.6.37",
   "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": "e6f36061d77555954c948125566850ef21af1debb21e0b65371876caa29768d4"
+  "contentHash": "9562cd3662884c9fb44cb61950299f9569a13ce38dc64101dc196b36e26d1c43"
 }

package/skills/campaign-builder/SKILL.md

@@ -32,6 +32,19 @@ Call `search` with `type="people"` and the criteria (include `filters={research_
 
 Iterate with the seller until the cohort is right ("too broad — only the US ones" → add the region attribute). This is the step to get right; everything after is mechanical.
 
+### Named-account sourcing handoff
+
+If the criteria names organizations/accounts and the preview has fewer people than needed, do not create an empty campaign or pretend the accounts are contacts. Hand off the missing-account cohort to `/pipeline-fill` discovery before Step 3:
+
+- Build `source_policy` using `pipeline-fill/contracts/source-policy.schema.json` from the installed skills bundle.
+- Preserve every explicit provider instruction. Example: "use Clay, no Sales Nav or CSV" becomes `selected_source: "clay"`, `source_mode: "preferred"`, `prohibited_sources: ["sales_nav", "linkedin", "csv"]`, and an ordered `allowed_fallbacks` list.
+- CSV and Sales Nav remain fully supported sources when the seller explicitly selects them. Source prohibitions are scoped to this run only; never turn one seller's preference into a global capability restriction or silently substitute a prohibited source.
+- Use the schema defaults unless the seller overrides them: company waves 10, person waves 5, and two retries for transient failures. `source_mode: "exclusive"` requires `allowed_fallbacks: []`.
+- Pass the named organizations and campaign criteria as the discovery ICP brief.
+- Set pipeline-fill `mode: "save"` explicitly. This persists approved people so their IDs can return here, but cannot enroll them or start outreach.
+- Let `/pipeline-fill` source companies first, resolve up to five matching people per company in bounded waves, preview the people, and return their IDs.
+- Resume here only with the approved person IDs. This handoff is sourcing only; it never launches outreach.
+
 ## Step 3: Create the campaign
 
 Two paths — ask which:
@@ -41,23 +54,39 @@ Two paths — ask which:
 
 ## Step 4: Assign the cohort
 
-Collect the person ids from the Step 2 preview (re-run the same `search` with a higher `limit` to get the full cohort if needed — paginate with `offset` for big cohorts) and call `manage_campaign` action=members id=<campaign uuid> payload={action: "add", person_ids: [...]}.
+Collect the person ids from the Step 2 preview (including IDs returned by the named-account handoff; re-run the same `search` with a higher `limit` to get the full cohort if needed — paginate with `offset` for big cohorts) and call `manage_campaign` action=members id=<campaign uuid> payload={action: "assign", person_ids: [...]}.
 
-For large cohorts, add in batches of a few hundred and report progress.
+For large cohorts, assign in bounded batches and report requested vs updated counts. If the response contains `requires_confirmation: true`, emit `state: "paused"` with code `research_confirmation_required`, stop, and show the preview to the seller. Never set `confirm: true` without their explicit confirmation. A source-campaign 403 is a visible failed item; a response that updates fewer people than requested is `state: "partial"` with code `research_partial`.
 
 ## Step 5: Review and launch — CONFIRMATION REQUIRED
 
 Show the seller a launch summary before anything sends:
 - Campaign name, source of messaging (cloned from X / fresh)
 - Cohort size and criteria
-- Channels and cadence (from the campaign config)
+- Channels, cadence, and maximum touches (from the campaign config). Enrollment schedules the first action immediately; spacing between later touches must already be represented in the campaign cadence.
 
-Then ask explicitly: "Launch outreach to these N people?" Only after a clear yes, call `manage_outreach` action=start id=[person uuids] (native bulk; payload optional {max_touches, allowed_channels, start_immediately}).
+Then ask explicitly: "Launch outreach to these N people?" Only after a clear yes, call `manage_outreach` action=start id=[person uuids] (native bulk; payload optional `{max_touches, allowed_channels}`). Do not pass `start_immediately`; the MCP intentionally ignores it.
 
 If the seller wants a dry run, stop after Step 4 — the campaign exists with members and nothing sends until plans start.
 
+### Existing Gmail scheduling
+
+If Gmail already contains scheduled or sent campaign emails, reconcile them before approving, drafting, or starting replacement email touches:
+
+1. Call `fetch` with `type=settings subtype=channel_status`. Select the intended sender mailbox from `channels.email.accounts[]` and use its public `id` as `account_id`; never invent or ask the seller for an internal provider id.
+2. Call `manage_messages` action=`reconcile_external_email`, id=<campaign uuid>, payload=`{account_id, action: "preview", after?, before?}`.
+3. Show exact matched, ambiguous, and unmatched counts. A preview is read-only.
+4. When the seller asked to synchronize—or explicitly approves the preview—apply that exact snapshot with payload=`{account_id, action: "apply", preview_id}`. Applying creates/finalizes Vruum reservations; it never sends or resends email.
+5. Pull payload=`{account_id, action: "exceptions"}` for the exception-first rescue queue. Never guess a recipient or silently release a reservation.
+
+Provider-scheduled rows are protected from duplicate dispatch and excluded from actionable review. Surface `externally_scheduled_count` when verifying the campaign.
+
+### Repairing already-created plans
+
+If the seller changes maximum touches or allowed channels after plans exist, update the cohort through `manage_outreach` action=`update`, id=[plan uuids], payload=`{max_touches?, allowed_channels?}`. This preserves each plan's active/paused state. Report per-plan success, error, and not-attempted counts; never patch outreach-plan rows directly in the database.
+
 ## Notes
 
 - Junk-safe personalization: contacts with garbage first names (single letters, org names) automatically get the no-name greeting variant — you don't need to filter them out of the cohort for that reason.
-- A person can be in many lists but holds ONE campaign assignment; adding to a campaign moves them. Say so if the cohort overlaps an active campaign — surface counts before Step 4.
+- A person can be in many lists but holds ONE campaign assignment; assigning to a campaign moves them. Say so if the cohort overlaps an active campaign — surface counts before Step 4.
 - Never call `manage_outreach` action=start without the Step 5 confirmation, and never auto-approve drafts; the outreach queue review (`/outreach-triage`) stays the quality gate.

package/skills/outreach-triage/SKILL.md

@@ -28,9 +28,16 @@ For small queues (5 or fewer) or when subagents can't access MCP, review directl
 
 ### Step 1: Get the lay of the land
 
-Call `fetch` with type=stats and subtype=outreach to see the pending queue shape. The response carries `needs_draft_count` (unauthored touches awaiting authoring) alongside `draft_count` (authored, awaiting approval) — surface both so the authoring backlog is visible up front. Present a quick summary:
+Call `fetch` with type=stats and subtype=outreach to see the pending queue shape, then call `get_outreach_review` with `content_length=preview, limit=1` for authoritative review-state counts. Surface:
 
-"You have N to author (needs_draft, W of them WARM accepted-connection follow-ups), X reply responses, Y pending T1s, Z T2+ follow-ups. [Any critical alerts.] Want me to run full triage or focus on a specific category?"
+- `needs_draft_count`: unauthored touches awaiting authoring
+- `draft_count`: authored touches awaiting approval
+- `approved_pending_send_count`: approved Vruum sends waiting on cadence/cooldown
+- `externally_scheduled_count`: Gmail/provider-scheduled rows protected by an external-send reservation
+
+Externally scheduled rows are intentionally excluded from actionable items. Never re-draft, approve, or manually resend them. Present a quick summary:
+
+"You have N to author (W WARM accepted-connection follow-ups), D drafts to review, A approved sends waiting on cadence, and E externally scheduled in Gmail. [Any critical alerts.] Want me to run full triage or focus on a specific category?"
 
 **Warm follow-ups outrank everything except replies.** The stats payload carries `needs_draft_warm_count`: unauthored `linkedin_message` touches to people who ACCEPTED the connection request. These are the highest-EV rows in the queue — a person who said yes to the invite is waiting on a first real message. When non-zero, lead the summary with it and default the triage order to: inbound replies → warm follow-ups → everything else.
 
@@ -38,6 +45,19 @@ Keep it short. The user knows their queue — they just need the numbers to deci
 
 **needs_draft items EXPIRE.** A nightly backend sweep (03:20 UTC) rejects any `needs_draft` row older than 14 days from creation — intended garbage collection, not an operator action. An expired touch is not lost forever (the plan reschedules and mints a fresh row about a week later), but the authoring work is deferred a cycle and the queue silently shrinks. The tools tell you: the stats payload carries `needs_draft_expiring_soon_count` (rows within 3 days of the sweep — surface it in the summary when non-zero), and each needs_draft item carries `expires_at` (its sweep deadline). Consequence for triage: author oldest-first, and if the queue is too big to clear in one session, clear the items closest to `expires_at` rather than sampling the freshest.
 
+### Gmail/Vruum reconciliation lane
+
+When the seller asks to audit or synchronize Gmail scheduling, do this before normal triage:
+
+1. Call `fetch` with `type=settings subtype=channel_status`. Select the intended sender mailbox from `channels.email.accounts[]` and use its public `id` as `account_id`; never invent or ask the seller for an internal provider id.
+2. Call `manage_messages` action=`reconcile_external_email`, id=<campaign uuid>, payload=`{account_id, action: "preview", after?, before?}`.
+3. Present matched, ambiguous, and unmatched counts. Preview is provider-read-only and mutation-free.
+4. If synchronization was requested or the seller approves the preview, call the same action with payload=`{account_id, action: "apply", preview_id}`. Apply only the exact preview; it creates/finalizes reservations without sending or resending anything.
+5. Call payload=`{account_id, action: "exceptions"}` and lead with blocked, ambiguous, unmatched, failed, or unverified contacts.
+6. Re-read `get_outreach_review` and verify `externally_scheduled_count` plus the actionable queue. A Gmail-scheduled row must never remain actionable.
+
+Manual Gmail edits require a fresh preview. Use guarded `hold`, `release`, or `mark_cancelled` only with the reservation id, a reason, and affirmative cancellation evidence or explicit human instruction. Reauthorization must preserve the provider identity and existing reservation; never create a replacement touch merely because the connector was refreshed.
+
 ### Step 2: Build the dispatch list and categorize
 
 Once the user says go (or picks a focus area), pull the lightweight message queue via `search` with type=messages, `fields=compact` and limit=100 — make THREE cheap calls: `warm_only=true, status=needs_draft, sort_by=expiring` (the WARM authoring lane — LinkedIn follow-ups to accepted connections, nearest deadline first), `status=needs_draft` (the full authoring lane; warm rows appear here too — dedupe by message_id, warm lane wins), and `status=draft` (the review lane). `fields=compact` returns message_id, person_name, category, sequence_number, channel, status, match_score, touches_completed, campaign_id, first_content_touch, and channel_rewrite_reason WITHOUT message content — very cheap on tokens. Tag each item with its status so dispatch routes it to the right mode: `needs_draft` → authoring, `draft` → review. (Omitting the status filter returns the default actionable set — needs_draft + draft + approved — but pull the two lanes explicitly so already-approved messages awaiting send don't enter triage.)
@@ -202,4 +222,5 @@ After outreach messages are processed, ask if the user wants to review the engag
 - **User wants to review a specific person:** pull that person's conversation with `fetch` (type=conversation) and review directly. No batch workflow.
 - **Subagent can't reach MCP tools:** fall back to inline review.
 - **Homogeneous T1 pattern:** if the first T1 batch all had the identical issue, fix the remaining in bulk with a single `manage_messages` call passing an id array (same action applied to every id, max 50 per call). Confirm first.
+- **Campaign plan settings drifted:** repair `max_touches` or `allowed_channels` through `manage_outreach` action=`update` with plan-id arrays. This preserves execution state; never update plan rows directly.
 

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

@@ -32,6 +32,43 @@ All harness source skills produce candidate lists matching this shape exactly. T
 - At minimum, each candidate needs **either** `linkedin_url` **or** (`name`-fields + `company`). Candidates with neither are skipped at Step 3.
 - `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.
+
+## Source-policy and recovery contract
+
+The canonical source policy is `contracts/source-policy.schema.json`. Validate it before
+inventorying providers. A selected source may not also be prohibited; exclusive mode
+has no fallbacks; ordered fallbacks may not contain prohibited sources. An explicitly
+selected disconnected source stops before the first external call.
+
+Every wave emits an object matching `contracts/run-progress.schema.json`, including
+`state`, `phase`, `wave`, `wave_count`, `completed`, `total`, `failed`,
+`not_attempted`, `safe_retry_items`, `ambiguous_items`, and `code`. A server 5xx puts
+the failing mutation in `ambiguous_items` because its commit status is unknown; only
+later not-attempted items go in `safe_retry_items`. Completed items are never replayed.
+
+Stable operator-visible codes:
+
+| Code | Meaning | Recovery |
+|---|---|---|
+| `source_policy_invalid` | contradictory or out-of-range policy | correct the named fields before any provider call |
+| `source_unavailable` | selected source is not connected | connect it or explicitly choose another source |
+| `source_prohibited` | attempted source violates policy | remove the call; never override implicitly |
+| `linkedin_identity_unresolvable` | profile is invalid/private/not found | use the next allowed structured fallback with the same `person_id` |
+| `linkedin_temporarily_unavailable` | timeout/429 after bounded retries | retry only the returned item later; do not switch silently |
+| `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 |
+| `person_not_visible` | supplied person is outside the caller's tenant | use a tenant-visible person or omit `person_id` |
+| `person_not_found` | tenant membership points to a missing person | refresh the candidate list |
+| `person_identity_conflict` | fallback identifier belongs to another person | remove the conflicting identifier and review the provider result |
+| `person_research_save_failed` | person research persistence failed with unknown commit status | inspect stored rows before any replay |
+| `source_campaign_forbidden` | caller cannot remove people from their current campaign | ask the source-campaign owner to move them |
+| `research_confirmation_required` | assignment requires explicit approval | pause and show the preview; never self-confirm |
+| `research_partial` | some items failed or were not attempted | resume only `safe_retry_items` |
+
+Backend response details link to `backend/app/domains/people/README.md#named-account-source-errors`.
 
 ---
 
@@ -85,11 +122,11 @@ acv_floor: {dollars or default $10K}
 Run your workflow (a–i) and return the structured output block.
 ```
 
-Each subagent returns: `company_id`, `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`.
+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.
 
 **Wait for the wave to complete before Phase B.** Phase B inputs depend on Phase A's signals (or null if failed).
 
-**Subagent timeout cascade (load-bearing):** when STATUS=failed for a company, the orchestrator does NOT skip the prospects from that company. Phase B still runs for them with `null` company signals. The harness pre-filter gate then tags them `harness_gate_status: gate_inconclusive` (a fourth status alongside pass/warming/low_priority/dismiss). `manage_person` action=save_discovered is still called — the backend's `MatchAnalysisAgent` may have cached company research from earlier runs and gates them appropriately. Surface gate-inconclusive prospects in the final report so the operator can re-run the failed companies later.
+**Subagent timeout cascade (load-bearing):** when STATUS=failed for a company, the orchestrator does NOT skip the prospects from that company. Phase B still runs for them with `null` company signals. The harness tags them `harness_gate_status: gate_inconclusive`; the Step 7 rubric gives zero company/ACV and outbound points, so their authoritative score cannot exceed 50 and the backend-enforced gate cannot enroll them. Save them for operator review and surface them in the final report so the operator can re-run the failed companies later.
 
 **Inter-wave progress line.** After each wave (5–10 subagents):
 ```
@@ -103,6 +140,8 @@ Helps operators distinguish "still working" from "stuck."
 
 **Concurrency cap: 5 parallel** (lowered from Phase A's 10 because Phase B subagents call `research` action=linkedin_fetch and the Unipile rate limiter throws over cap — see `backend/app/domains/channels/services/unipile/rate_limiter.py:36`. Lower concurrency keeps us under the per-account window.)
 
+**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` to `research(action="save_person")`. 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 prompt template:
@@ -128,7 +167,7 @@ acv_floor: {dollars}
 Run your workflow (a–k) and return the structured output block. Note: do NOT call manage_person action=save_discovered or manage_outreach action=start — those are orchestrator-only and not in your tools list.
 ```
 
-Each subagent returns: `topics_of_interest`, `recent_posts`, `opening_hooks[]` (2–3, with source URLs), `decision_maker_level` (junior/mid/senior), `email_status` (found/pending), `role_start_date`, per-prospect `triggers[]`, `STATUS`. Note: `person_id` is NOT returned here — identity resolution happens in Step 7.
+Each subagent returns: `first_name`, `last_name`, `email`, `linkedin_url`, `title`, `company_name`, `company_domain`, `company_website`, `company_linkedin_url`, `topics_of_interest`, `recent_posts`, `opening_hooks[]` (2–3, with source URLs), `decision_maker_level` (junior/mid/senior), `email_status` (found/pending), `role_start_date`, per-prospect `triggers[]`, `STATUS`. Every `recent_posts` item uses the backend shape `{text, posted_at?, share_url?, reaction_count?, comment_count?}`; never send the retired `content`, `url`, `excerpt`, or `date` keys. Note: `person_id` is NOT returned here — identity resolution happens in Step 7.
 
 **Inter-wave progress line:**
 ```
@@ -139,7 +178,7 @@ Each subagent returns: `topics_of_interest`, `recent_posts`, `opening_hooks[]` (
 
 ## Step 6 — Harness pre-filter gate (orchestrator-side, pre-save)
 
-This is a **coarse pre-filter** — its job is to avoid wasted backend save calls (`manage_person` action=save_discovered) on obvious dismisses. The **authoritative** gate is server-side `MatchAnalysisAgent.match_score >= 70` and runs inside that save call. The harness gate cannot override the backend gate; it can only dismiss before reaching it.
+This is the categorical first half of the harness-authoritative gate. It avoids wasted backend saves for obvious dismisses and feeds the deterministic numeric assessment in Step 7c. The backend does not re-score a supplied assessment; it records the harness score and mechanically enforces `match_score >= 70`. `MatchAnalysisAgent` is fallback-only for newly added people when callers omit assessment; duplicates retain their stored score unless a campaign move enqueues an asynchronous re-score.
 
 Per surviving prospect, evaluate four criteria using the campaign's playbook ICP and the Phase A + Phase B signals:
 
@@ -149,7 +188,7 @@ Per surviving prospect, evaluate four criteria using the campaign's playbook ICP
 
 ### 2. Outbound motion or hiring signal?
 - `outbound_motion_score > 0` OR explicit hiring trigger present → pass
-- If no → flag `warming_candidate` (still call `manage_person` action=save_discovered — operator may want to warm-track them; backend match analysis tells us if the campaign fit is real)
+- If no → flag `warming_candidate` (still call `manage_person` action=save_discovered — operator may want to warm-track them; the Step 7 rubric records the weaker fit honestly)
 
 ### 3. Decision-maker level senior?
 - `decision_maker_level == senior` → pass
@@ -175,10 +214,16 @@ For non-dismiss outcomes, also set `dismiss_reason` to null and `flag` to the re
 
 ## Step 7 — Save chain (everyone except harness-gate dismisses)
 
+Apply the requested mode before any persistence:
+
+- `research-only`: stop before Step 7a. Return the researched preview and do not call `save_company`, `save_person`, `save_discovered`, or `manage_outreach`.
+- `save`: run Steps 7a–7c, but call `save_discovered` **without** `campaign_id`. This persists the tenant-visible prospect and gate result without assigning a campaign or starting outreach.
+- `save-and-enroll`: run the full chain. Pass `campaign_id` to `save_discovered`, then include passing prospects in Step 7d.
+
 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={company_name, domain, funding_data, growth_metrics, current_priorities})`. Skip if `CACHE_HIT: true` for that 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.
 
 ### b. Identity resolution + person research (load-bearing — corrects Codex Finding #6)
 
@@ -215,12 +260,56 @@ If the prospect's company isn't already cached and Phase A produced fresh resear
    - If the prospect already had `person_id` set on the candidate (e.g. operator pasted a Vruum person UUID), pass it explicitly in the payload: `research(action="save_person", payload={person_id: ..., ...})` — backend updates rather than creating a new record.
    - The response includes the `person_id`. Capture it for step c.
 
-### c. Save discovered person (the backend authoritative gate runs here)
+### c. Save discovered person (authoritative harness score, backend-enforced gate)
+
+Build the authoritative `assessment` from the campaign playbook plus Phase A/B evidence. Score mechanically so reruns agree:
+
+- Company/ACV fit: 30 points when the known ACV class meets the campaign floor; a known miss is a harness dismiss and never reaches Step 7.
+- Buying authority: 25 senior, 15 mid; a junior with no senior replacement is dismissed.
+- Outbound/hiring motion: 20 when present, otherwise 0 and tag `warming`.
+- Recent timing trigger: 15 when present, otherwise 0 and tag `low_priority`.
+- Evidence strength: 10 for a verified profile plus at least two cited sources, 5 for partial cited evidence, 0 for unverified evidence.
+- `gate_inconclusive` gets 0 for unknown company/ACV and outbound criteria, so it cannot exceed 50 without fresh company evidence.
+
+The score is the sum (0–100); 70+ passes. Send this exact shape:
+
+```json
+{
+  "match_score": 85,
+  "match_summary": "Two or three evidence-backed sentences against this campaign's ICP.",
+  "alignment_points": [
+    {
+      "point": "Specific alignment",
+      "evidence": "Cited fact and URL",
+      "confidence": 0.8,
+      "source_type": "harness_research"
+    }
+  ],
+  "concerns": [
+    {
+      "concern": "Specific gap",
+      "evidence": "Cited or explicitly missing evidence",
+      "severity": "blocker|warning|minor"
+    }
+  ],
+  "why_now": "Timing rationale with source",
+  "recommended_approach": "Campaign-relevant approach",
+  "overall_confidence": 0.8,
+  "scored_by": "harness:pipeline-fill"
+}
+```
+
+`match_summary` must be non-empty. Alignment items require `point` and `evidence`; concern items require `concern` and `evidence`. Confidence values are 0–1 and concern severity is exactly `blocker`, `warning`, or `minor`.
+
+Then call `manage_person(action="save_discovered", payload={person_id: <from b>, assessment: <object above>, ...})`:
+
+- `mode == save`: add `assessment_campaign_id: <campaign>` so the score is recorded against the campaign ICP, and omit `campaign_id` so no assignment or move occurs. New rows remain unassigned; duplicates keep their existing campaign assignment.
+- `mode == save-and-enroll`: add `campaign_id: <campaign>`; the backend uses it for both assessment provenance and assignment. Omit `assessment_campaign_id` unless it is the same campaign.
 
-Call `manage_person(action="save_discovered", payload={person_id: <from b>, campaign_id: ...})`. This:
-- Runs server-side `analyze_person_match` + signal eval
+This:
+- Records the harness assessment as authoritative and skips the backend LLM scorer
 - Returns `match_score` (0–100) and `quality_gate_pass` (bool, true iff `match_score >= 70`)
-- Writes the `company_people` row that puts the prospect into the campaign
+- Writes the tenant's `company_people` row; campaign assignment happens only when the payload includes `campaign_id`
 
 **Distinguish two failure modes (Codex Finding #9):**
 - **Request failure (5xx, timeout, network):** retry once with 2s backoff. If still failing, leave the prospect in `discovery_failed` status and surface in the final report. **Don't** claim "saved as gate-fail" — the row was never written.
@@ -256,7 +345,7 @@ Harness pre-filter gate:
   gate_inconclusive : {N}
   dismiss      : {N}  (top reasons: acv_too_low={N}, decision_maker_junior={N})
 
-Backend authoritative gate (match_score >= 70):
+Backend-enforced gate using the authoritative harness score (match_score >= 70):
   passed       : {N}
   failed       : {N}  (saved with research; operator can review via /enrich-prospect)
   request_failed : {N}  (retry candidates — surface in next run)
@@ -281,9 +370,9 @@ For multi-campaign runs, group the report by campaign and include a totals summa
 ## Edge cases + failure handling reference
 
 - **Source returns empty after dedup** — orchestrator says "All {N} candidates already in pipeline, nothing to research" and exits cleanly.
-- **Mid-flight cancellation** (operator Ctrl+C between Phase A and Phase B) — Phase A research is saved server-side. Re-running `/pipeline-fill` for the same campaign + source picks up via batch dedup; no re-research of cached companies. Note this in the cancellation message.
-- **Subagent timeout cascade** — Phase A failed for a company → Phase B runs degraded → harness gate marks `gate_inconclusive` → backend decides via cached company research. See Step 4.
-- **Two-gate disagreement** — harness pass + backend fail (or vice versa) → see Step 7c. Stricter outcome wins for enrollment; both states surfaced in the report.
+- **Mid-flight cancellation** (operator Ctrl+C before Step 7) — no new Phase A/B research has been persisted. Re-running `/pipeline-fill` reuses pre-existing fresh cache entries but repeats unfinished research waves. Note this honestly in the cancellation message.
+- **Subagent timeout cascade** — Phase A failed for a company → Phase B runs degraded → harness marks `gate_inconclusive` → Step 7 score is capped below the backend threshold. See Step 4.
+- **Categorical/numeric divergence** — a categorical `pass` can still score below 70 when evidence strength is weak. Enrollment requires both `harness_gate_status == pass` and backend `quality_gate_pass == true`; surface both states.
 - **Cached company research >90 days old** — Phase A re-runs the company subagent. Don't trust stale signals for an active fill.
 - **Manual-list cap** — if >100 lines pasted, orchestrator asks "{N} prospects pasted — process all, or first M? (a/N)".
 - **CSV >200 rows** — same prompt at Step 5 of csv-pipeline-fill.

package/skills/pipeline-fill/SKILL.md

@@ -14,7 +14,7 @@ You are a source-agnostic pipeline filler. You pick campaigns to fill, pick a so
 
 ## 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), pre-filters against campaign ICP, then saves the qualified ones into the campaign via the backend's canonical 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, 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
 
@@ -51,13 +51,15 @@ The orchestrator's MCP precheck at the top of Step 3 (the `fetch` type=research_
 ## Inputs
 
 - `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.
 - `mode`: `research-only` | `save` | `save-and-enroll` (default: `save-and-enroll`).
-- `gate_threshold`: minimum backend `match_score` to enroll (default: campaign's existing quality_gate).
 
 ## Workflow — Step 1: Show pipeline status & pick campaigns
 
-Call `import_prospects(action="sales_nav_searches", payload={action: "list"})` + `fetch(type="stats", subtype="outreach")` for queue depth + `search(type="campaigns")` for non-Sales-Nav campaigns. Present a numbered table with **per-campaign ETA**:
+Always call `fetch(type="stats", subtype="outreach")` for queue depth and `search(type="campaigns")` for campaign status. Call `import_prospects(action="sales_nav_searches", payload={action: "list"})` **only** when the operator explicitly selected Sales Nav and `source_policy.prohibited_sources` does not contain `sales_nav` or `linkedin`. A generic status check must never touch Sales Nav.
+
+Present a numbered table with **per-campaign ETA**:
 
 ```
 Pipeline status:
@@ -88,6 +90,8 @@ ETA estimates: ~2s for batch Step 3 dedup + ~30s/wave Phase A + ~60s/wave Phase
 
 > Sourcing {campaign_name} via discovery (ICP-based, long-tail). Reply `sales-nav`, `yc`, `csv`, or `picker` to switch.
 
+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.
+
 Why discovery is the default: keyword/Sales-Nav sources keep returning the same marquee names, which collide with already-enrolled prospects as a campaign matures — the Step 3 dedup then throws most of the batch away. Discovery anchors on the campaign's own ICP and reaches the long tail, deduping *before* research instead of after. Only render the full picker below when the operator asks to choose (`picker`), names a non-discovery source, or the discovery handler can't proceed.
 
 Per selected campaign, when the operator wants to choose the source explicitly, prompt:
@@ -141,12 +145,16 @@ Operator gives a brief like "Series A-C SaaS founders, US, 50-500 ppl" or "direc
    - **Email finder** — Hunter via `search type=companies {domain, seniority}`, or the provider's own email step — to fill the contact emails Phase B needs.
    - **Web** (`WebSearch` / `WebFetch`) — always available; the universal fallback and a strong long-tail *company* finder (funding announcements, Crunchbase/PitchBook, vertical directories) even when a data provider is connected.
 
-   Announce the pick in one line ("Sourcing via Clay — firmographic pull + committee enrichment; web as backup") so the operator can redirect. If no enrichment provider is connected, say so and fall back to web + Hunter.
+   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.
 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.
 
+Emit progress objects matching `contracts/run-progress.schema.json` after every bounded wave. Company-provider actions run in waves of at most 10; person/LinkedIn/provider contact actions run in waves of at most 5. Never submit a mixed unbounded batch and wait without a progress update.
+
+Defaults when `source_policy` is omitted: `selected_source: null` (inventory connected discovery tools), `source_mode: "preferred"`, `prohibited_sources: []`, `allowed_fallbacks: ["web"]`, `company_wave_size: 10`, `person_wave_size: 5`, and `transient_retry_attempts: 2`. Operator language such as "no Sales Nav" or "no CSV" is parsed into `prohibited_sources` before validation and overrides defaults.
+
 Discovery-path candidates produced in either path use the canonical shape in `RESEARCH-ENGINE.md` and feed into Step 3 the same way.
 
 **Path detection:** if the first non-comment line looks like a URL or has commas (paste-shaped), use Path A. If it's prose without URLs/commas and >40 chars, use Path B. If ambiguous, ask: "paste, or describe the ICP and I discover?"
@@ -161,5 +169,5 @@ Do not duplicate the engine logic in this skill — link operators back to the e
 
 - **Composability** with source skills: source skills produce candidate lists; this orchestrator runs the research engine. Both directions allowed (operator can run a source skill standalone or run /pipeline-fill as the front door).
 - **Real money costs** are in Phase B (LinkedIn API + Hunter calls + OpenAI tokens for the prospect subagent). Phase A is mostly WebFetch/WebSearch which is operator-network. The batch primitives in Step 3 keep dedup latency low (~2s vs 12s pre-batch).
-- **Harness offload framing**: deep research runs in your IDE (your tokens). The backend `MatchAnalysisAgent` runs the canonical gate (~$0.02/prospect on Vruum's bill). This split is intentional — see memory `project_harness_offload_strategy.md`.
+- **Harness offload framing**: deep research and the authoritative campaign score run in your IDE (your tokens). The backend validates the payload, records provenance, and mechanically enforces `match_score >= 70`; `MatchAnalysisAgent` is fallback-only for newly added people when a caller omits assessment. Duplicates retain their stored score unless a campaign move enqueues an asynchronous re-score.
 - **Audit trail**: every run writes to `.context/runs/pipeline-fill-{ISO-timestamp}.md`. Useful weeks later for "what did the YC fill on Apr 12 import?"

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

@@ -0,0 +1,95 @@
+{
+  "source_policies": {
+    "clay_without_sales_nav": {
+      "version": "1",
+      "selected_source": "clay",
+      "source_mode": "preferred",
+      "prohibited_sources": [
+        "sales_nav",
+        "linkedin",
+        "csv"
+      ],
+      "allowed_fallbacks": [
+        "web",
+        "hunter"
+      ],
+      "company_wave_size": 10,
+      "person_wave_size": 5,
+      "transient_retry_attempts": 2,
+      "reason": "Named-account sourcing requested through Clay."
+    },
+    "clay_exclusive": {
+      "version": "1",
+      "selected_source": "clay",
+      "source_mode": "exclusive",
+      "prohibited_sources": [
+        "sales_nav",
+        "linkedin",
+        "csv"
+      ],
+      "allowed_fallbacks": [],
+      "company_wave_size": 10,
+      "person_wave_size": 5,
+      "transient_retry_attempts": 2,
+      "reason": "Use only Clay; stop if it is unavailable."
+    }
+  },
+  "progress": {
+    "company_wave": {
+      "version": "1",
+      "state": "running",
+      "phase": "company_research",
+      "provider": "clay",
+      "wave": 1,
+      "wave_count": 1,
+      "completed": 7,
+      "total": 7,
+      "failed": 0,
+      "not_attempted": 0,
+      "safe_retry_items": [],
+      "ambiguous_items": [],
+      "code": null,
+      "elapsed_seconds": 34,
+      "eta_seconds": 0
+    },
+    "person_wave": {
+      "version": "1",
+      "state": "partial",
+      "phase": "person_research",
+      "provider": "clay",
+      "wave": 2,
+      "wave_count": 4,
+      "completed": 9,
+      "total": 20,
+      "failed": 1,
+      "not_attempted": 10,
+      "safe_retry_items": [
+        "person-11",
+        "person-12",
+        "person-13",
+        "person-14",
+        "person-15",
+        "person-16",
+        "person-17",
+        "person-18",
+        "person-19",
+        "person-20"
+      ],
+      "ambiguous_items": [
+        "person-10"
+      ],
+      "code": "research_partial",
+      "elapsed_seconds": 58,
+      "eta_seconds": null
+    }
+  },
+  "recent_posts": [
+    {
+      "text": "We are opening a new clinic.",
+      "posted_at": "2026-07-20T14:00:00Z",
+      "share_url": "https://www.linkedin.com/feed/update/urn:li:activity:1",
+      "reaction_count": 12,
+      "comment_count": 3
+    }
+  ]
+}

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

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://vruum.ai/contracts/pipeline-fill/run-progress.schema.json",
+  "title": "Pipeline Fill Run Progress",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "state",
+    "phase",
+    "wave",
+    "wave_count",
+    "completed",
+    "total",
+    "failed",
+    "not_attempted",
+    "safe_retry_items",
+    "ambiguous_items",
+    "code"
+  ],
+  "properties": {
+    "version": {
+      "const": "1"
+    },
+    "state": {
+      "enum": [
+        "running",
+        "completed",
+        "partial",
+        "paused",
+        "failed"
+      ]
+    },
+    "phase": {
+      "enum": [
+        "company_research",
+        "person_research",
+        "assignment"
+      ]
+    },
+    "provider": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "wave": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "wave_count": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "completed": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "total": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "failed": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "not_attempted": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "safe_retry_items": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          {
+            "type": "string",
+            "minLength": 1
+          },
+          {
+            "type": "integer",
+            "minimum": 0
+          },
+          {
+            "type": "object"
+          }
+        ]
+      }
+    },
+    "ambiguous_items": {
+      "type": "array",
+      "description": "Failed mutations whose commit status is unknown; inspect before replaying.",
+      "items": {
+        "oneOf": [
+          {
+            "type": "string",
+            "minLength": 1
+          },
+          {
+            "type": "integer",
+            "minimum": 0
+          },
+          {
+            "type": "object"
+          }
+        ]
+      }
+    },
+    "code": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "elapsed_seconds": {
+      "type": "number",
+      "minimum": 0
+    },
+    "eta_seconds": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "minimum": 0
+    }
+  }
+}

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

@@ -0,0 +1,399 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://vruum.ai/contracts/pipeline-fill/source-policy.schema.json",
+  "title": "Pipeline Fill Source Policy",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "selected_source",
+    "source_mode",
+    "prohibited_sources",
+    "allowed_fallbacks",
+    "company_wave_size",
+    "person_wave_size",
+    "transient_retry_attempts"
+  ],
+  "properties": {
+    "version": {
+      "const": "1"
+    },
+    "selected_source": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/provider"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null
+    },
+    "source_mode": {
+      "enum": [
+        "preferred",
+        "exclusive"
+      ],
+      "default": "preferred"
+    },
+    "prohibited_sources": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/provider"
+      },
+      "uniqueItems": true,
+      "default": []
+    },
+    "allowed_fallbacks": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/provider"
+      },
+      "uniqueItems": true,
+      "default": [
+        "web"
+      ]
+    },
+    "company_wave_size": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 10,
+      "default": 10
+    },
+    "person_wave_size": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 5,
+      "default": 5
+    },
+    "transient_retry_attempts": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 2,
+      "default": 2
+    },
+    "reason": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "$defs": {
+    "provider": {
+      "enum": [
+        "clay",
+        "sales_nav",
+        "linkedin",
+        "csv",
+        "yc",
+        "web",
+        "hunter",
+        "manual"
+      ]
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "source_mode": {
+            "const": "exclusive"
+          }
+        },
+        "required": [
+          "source_mode"
+        ]
+      },
+      "then": {
+        "properties": {
+          "allowed_fallbacks": {
+            "maxItems": 0
+          }
+        }
+      }
+    },
+    {
+      "not": {
+        "anyOf": [
+          {
+            "properties": {
+              "selected_source": {
+                "const": "clay"
+              },
+              "prohibited_sources": {
+                "contains": {
+                  "const": "clay"
+                }
+              }
+            },
+            "required": [
+              "selected_source",
+              "prohibited_sources"
+            ]
+          },
+          {
+            "properties": {
+              "selected_source": {
+                "const": "sales_nav"
+              },
+              "prohibited_sources": {
+                "contains": {
+                  "const": "sales_nav"
+                }
+              }
+            },
+            "required": [
+              "selected_source",
+              "prohibited_sources"
+            ]
+          },
+          {
+            "properties": {
+              "selected_source": {
+                "const": "linkedin"
+              },
+              "prohibited_sources": {
+                "contains": {
+                  "const": "linkedin"
+                }
+              }
+            },
+            "required": [
+              "selected_source",
+              "prohibited_sources"
+            ]
+          },
+          {
+            "properties": {
+              "selected_source": {
+                "const": "csv"
+              },
+              "prohibited_sources": {
+                "contains": {
+                  "const": "csv"
+                }
+              }
+            },
+            "required": [
+              "selected_source",
+              "prohibited_sources"
+            ]
+          },
+          {
+            "properties": {
+              "selected_source": {
+                "const": "yc"
+              },
+              "prohibited_sources": {
+                "contains": {
+                  "const": "yc"
+                }
+              }
+            },
+            "required": [
+              "selected_source",
+              "prohibited_sources"
+            ]
+          },
+          {
+            "properties": {
+              "selected_source": {
+                "const": "web"
+              },
+              "prohibited_sources": {
+                "contains": {
+                  "const": "web"
+                }
+              }
+            },
+            "required": [
+              "selected_source",
+              "prohibited_sources"
+            ]
+          },
+          {
+            "properties": {
+              "selected_source": {
+                "const": "hunter"
+              },
+              "prohibited_sources": {
+                "contains": {
+                  "const": "hunter"
+                }
+              }
+            },
+            "required": [
+              "selected_source",
+              "prohibited_sources"
+            ]
+          },
+          {
+            "properties": {
+              "selected_source": {
+                "const": "manual"
+              },
+              "prohibited_sources": {
+                "contains": {
+                  "const": "manual"
+                }
+              }
+            },
+            "required": [
+              "selected_source",
+              "prohibited_sources"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "not": {
+        "anyOf": [
+          {
+            "properties": {
+              "allowed_fallbacks": {
+                "contains": {
+                  "const": "clay"
+                }
+              },
+              "prohibited_sources": {
+                "contains": {
+                  "const": "clay"
+                }
+              }
+            },
+            "required": [
+              "allowed_fallbacks",
+              "prohibited_sources"
+            ]
+          },
+          {
+            "properties": {
+              "allowed_fallbacks": {
+                "contains": {
+                  "const": "sales_nav"
+                }
+              },
+              "prohibited_sources": {
+                "contains": {
+                  "const": "sales_nav"
+                }
+              }
+            },
+            "required": [
+              "allowed_fallbacks",
+              "prohibited_sources"
+            ]
+          },
+          {
+            "properties": {
+              "allowed_fallbacks": {
+                "contains": {
+                  "const": "linkedin"
+                }
+              },
+              "prohibited_sources": {
+                "contains": {
+                  "const": "linkedin"
+                }
+              }
+            },
+            "required": [
+              "allowed_fallbacks",
+              "prohibited_sources"
+            ]
+          },
+          {
+            "properties": {
+              "allowed_fallbacks": {
+                "contains": {
+                  "const": "csv"
+                }
+              },
+              "prohibited_sources": {
+                "contains": {
+                  "const": "csv"
+                }
+              }
+            },
+            "required": [
+              "allowed_fallbacks",
+              "prohibited_sources"
+            ]
+          },
+          {
+            "properties": {
+              "allowed_fallbacks": {
+                "contains": {
+                  "const": "yc"
+                }
+              },
+              "prohibited_sources": {
+                "contains": {
+                  "const": "yc"
+                }
+              }
+            },
+            "required": [
+              "allowed_fallbacks",
+              "prohibited_sources"
+            ]
+          },
+          {
+            "properties": {
+              "allowed_fallbacks": {
+                "contains": {
+                  "const": "web"
+                }
+              },
+              "prohibited_sources": {
+                "contains": {
+                  "const": "web"
+                }
+              }
+            },
+            "required": [
+              "allowed_fallbacks",
+              "prohibited_sources"
+            ]
+          },
+          {
+            "properties": {
+              "allowed_fallbacks": {
+                "contains": {
+                  "const": "hunter"
+                }
+              },
+              "prohibited_sources": {
+                "contains": {
+                  "const": "hunter"
+                }
+              }
+            },
+            "required": [
+              "allowed_fallbacks",
+              "prohibited_sources"
+            ]
+          },
+          {
+            "properties": {
+              "allowed_fallbacks": {
+                "contains": {
+                  "const": "manual"
+                }
+              },
+              "prohibited_sources": {
+                "contains": {
+                  "const": "manual"
+                }
+              }
+            },
+            "required": [
+              "allowed_fallbacks",
+              "prohibited_sources"
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}

package/skills/vruum-guide/SKILL.md

@@ -33,6 +33,7 @@ Build "your revenue engine today" from live reads — never from memory or assum
 - `search` type=people limit=1 filters={research_status: "all"} → total contacts (read the total, not the rows)
 - `search` type=deals limit=5 → deal pipeline existence
 - `fetch` type=stats subtype=outreach → sends, replies, meetings
+- `get_outreach_review` content_length=preview limit=1 → actionable, approved-pending-send, and externally scheduled counts
 - `search` type=content → whether an organic content motion is active
 
 Present a compact snapshot (5-8 lines, their numbers), positioned on the revenue-motion map (Step 2). If the company record or knowledge base shows a referral source ("referred by X"), acknowledge it and skip intake questions that referral context already answers.
@@ -64,6 +65,7 @@ Important boundaries: outreach/reply/content/comment prose is authored in the ha
 | Signal | Recommendation |
 |---|---|
 | Contacts sitting unenrolled | enroll into a campaign (`/campaign-builder` or `manage_campaign` action=members) |
+| Gmail/provider-scheduled rows or reconciliation exceptions | `/outreach-triage` Gmail/Vruum reconciliation lane; never recreate the email |
 | Outreach queue has pending drafts | `/outreach-triage` |
 | Engagement queue non-empty | `/engagement-triage` |
 | Replies without follow-up | `/diagnose-reply` on the interesting ones, then respond |