@sellable/mcp 0.1.0

package/skills/create-campaign-v2/references/step-13-import-leads.md

@@ -0,0 +1,151 @@
+# Step 13 — Import Leads Contract
+
+This reference governs Step 13 (`auto-execute-leads`) of the Plan 85-02
+autonomous tail. Load before calling `import_leads` and on every resume
+into Step 13.
+
+## Principle
+
+Bounded review-batch sourcing + import happens AFTER atomic mint, not during.
+The commit gate never calls `import_leads`; Step 13 is where the first real
+review batch is pulled into the workspace. Do not spend credits on the full
+source list until the user reviews the first batch and explicitly approves
+expansion.
+
+## Resolve Approved Source
+
+Before importing, read `lead-source-intake.json` if it exists. Treat it as a
+manifest, not a suggestion. Revalidate file metadata and confirmation tokens on
+resume, and persist/recover materialized IDs so retries do not duplicate
+source lead lists, searches, campaign table rows, or queued cells.
+
+Supported branches:
+
+- **No manifest / normal discovery** — use the existing provider import path.
+- **Supplied LinkedIn profile CSV** — confirm `load_csv_linkedin_leads` only
+  after approval, then import into the campaign table with
+  `confirm_lead_list({ sourceLeadListId, targetLeadCount: importLimit })`.
+  Do **not** call `wait_for_lead_list_ready` for this branch; there is no
+  provider import job to wait on, and probing readiness can leave the campaign
+  in an import-failed state before `confirm_lead_list`.
+- **Existing Sellable lead list** — revalidate the source list in the same
+  workspace, then reuse it with
+  `confirm_lead_list({ sourceLeadListId, targetLeadCount: importLimit })`.
+  Do **not** call `wait_for_lead_list_ready` for this branch.
+- **Supplied domain/account CSV** — reuse or confirm `load_csv_domains`, keep
+  its `domainFilterId`, run a campaign-associated Prospeo people search with
+  `campaignOfferId`, provider prompt preflight, and `domainFilterId`, then
+  import the review batch from that search.
+
+If the source file changed after preview, or the existing list is missing or
+wrong-workspace, escalate before materialization. If a supplied-domain search
+returns zero or too few usable people, preserve `domainFilterId` and ask
+whether to widen role filters, add more domains, or abort. Never silently drop
+the domain constraint.
+
+## First-Import Path
+
+Default case — no existing lead list bound to the campaign:
+
+```text
+import_leads({
+  campaignOfferId,
+  targetLeadCount: <importLimit from auto-execute.yaml; default 25>
+})
+```
+
+Provider is inherited from the Phase 84 commit decision (not re-selected
+here). Response returns `{ imported, skipped, duplicates }` — surface all
+three to the escalation logic so dedup ratios are visible.
+
+For supplied direct lists, `confirm_lead_list` must receive
+`targetLeadCount: <importLimit>` or explicit `sourceRowIds` so a 100-row source
+imports only the bounded review batch before greenlight.
+
+## `mode=add` Two-Step Handshake
+
+When importing into an existing workflow table (e.g. signal-discovery
+overlay onto an existing Sales Nav cohort), `import_leads` with
+`mode=add` requires a two-step handshake:
+
+### Step 1 — First call returns `needsModeSelection=true`
+
+```text
+import_leads({
+  campaignOfferId,
+  mode: "add",
+  targetLeadCount: ...
+})
+```
+
+Response:
+
+```text
+{
+  needsModeSelection: true,
+  existingLeadListId: "lead_list_xyz",
+  ...
+}
+```
+
+This is NOT an error. It's the handshake. Do NOT retry the same call.
+Do NOT treat this as a failure. Capture `existingLeadListId`.
+
+### Step 2 — Second call passes `sourceLeadListId`
+
+```text
+import_leads({
+  campaignOfferId,
+  mode: "add",
+  sourceLeadListId: existingLeadListId,
+  targetLeadCount: ...
+})
+```
+
+Response: actual import result `{ imported, skipped, duplicates }`.
+
+## Dedup Ratio Surfacing
+
+`import_leads` can produce wildly different outcomes depending on prior
+imports into the same campaign. Surface all three counters to the tail
+so escalation can distinguish "lane exhausted" from "good-looking import":
+
+- **imported** — new rows added to the cohort
+- **skipped** — rows that matched dedup keys (already in list)
+- **duplicates** — rows that were in the raw pull but rejected by dedup
+
+### Interpretation
+
+| imported   | skipped    | Interpretation                                      |
+| ---------- | ---------- | --------------------------------------------------- |
+| near limit | low        | Fresh lane; good pull                               |
+| low        | near limit | Lane mostly exhausted (dedup against prior imports) |
+| 0          | high       | Lane fully exhausted — escalate as "lane exhausted" |
+| 0          | 0          | Real zero-lead case — escalate as "hard fail"       |
+
+Observed signal-discovery run: 911 scraped / 548 skipped / 363 imported
+(≈40% fresh). That's a "good-looking import" not a lane-exhausted
+state — escalation should NOT fire.
+
+## Zero-Leads Escalation
+
+Per `escalation-ladder.md` condition #1: if `import_leads` returns 0
+usable rows (imported = 0, skipped = 0), hard-fail escalate.
+
+Distinction: 0 imported but high skipped = lane exhausted; this is NOT a
+hard fail but DOES warrant surfacing to the operator — the campaign
+cannot scale further without a new source lane.
+
+## Hard Rules
+
+- `import_leads` with `mode=add` is ALWAYS a two-step handshake. Never
+  treat the first `needsModeSelection=true` response as a failure.
+- Dedup ratios (imported / skipped / duplicates) are always surfaced for
+  escalation-logic input.
+- Zero-imported + zero-skipped ⇒ hard-fail escalate.
+- Zero-imported + high-skipped ⇒ lane-exhausted operator notice (NOT a
+  silent proceed).
+- `import_leads` is NOT called in atomic mint. Only in Step 13.
+- `import_leads` is NOT called again in Step 14 (validate-sample). Full
+  cohort import is a Step 13 action, not a recovery action for a bad
+  sample.

package/skills/create-campaign-v2/references/step-15-re-cascade.md

@@ -0,0 +1,90 @@
+# Step 15 — Message Re-Cascade Contract
+
+This reference governs Step 15 (`auto-execute-messaging`) re-cascade
+behavior when Step 14's validate-sample loop graduates additional rows
+from pending → passed after the first `generate_messages` call has
+already run.
+
+Load whenever Step 15 is about to transition to
+`awaiting-user-greenlight`, and on every resume into Step 15.
+
+## Principle
+
+Generate Message cells are cascade-scoped. If Step 14's rubric flips rows
+from pending → passed AFTER Step 15 first observes messages for the review
+batch, the new rows can sit pending with no message. Step 15 must explicitly
+queue the newly-pending Generate Message cells for the review-batch subset.
+
+Observed on manual Phase-85 signal-discovery run (2026-04-20): 15 new
+rows graduated pending → passed mid-tail while `messagesCount` stayed
+flat at 257. The new rows never got messages.
+
+## When Re-Cascade Fires
+
+Re-cascade runs whenever ALL of the following are true:
+
+1. Step 15 has already observed the initial review-batch message cascade.
+2. A subsequent check of rubric state shows rows that were pending at
+   first generate_messages time are now passed.
+3. Those newly-passed rows do NOT yet have generated messages
+   (`messagesCount` flat relative to pre-cascade).
+4. Step 15 has NOT yet transitioned to `awaiting-user-greenlight`.
+
+If condition 4 already fired (i.e. we're in Step 16), the re-cascade
+runs on resume into Step 15 if validate-sample was re-entered and new
+rows graduated.
+
+## Re-Cascade Loop Shape
+
+```text
+1. paginate campaign table (get_rows_minimal, strip carryData) to
+   collect rowIds where:
+     - rubricStatus = "passed"
+     - messageStatus = "pending" OR messagesCount = 0
+
+2. if newlyPassedRowIds.length == 0:
+     proceed to awaiting-user-greenlight
+     EXIT re-cascade loop
+
+3. else:
+     queue_cells({
+       tableId,
+       cellIds: newlyPassedGenerateMessageCellIds
+     })
+
+4. re-check token contract on the cascaded subset (strict mode default)
+   — see references/thomas-revision-filters.md + gold-standard-message-patterns.md
+
+5. go back to step 1 until newlyPassedRowIds == 0
+```
+
+## Cap
+
+Re-cascade must not loop indefinitely. Cap at 3 cascade iterations —
+if after 3 cascades the newly-passed set is still growing, escalate
+(the validate-sample loop is likely mis-configured or the rubric is
+flapping).
+
+## Interaction with Critique
+
+When `messaging.critique.enabled=true`, the critique + finalizer pass
+applies to the re-cascade subset same as the initial cohort. Budget
+caps (`messaging.critique.budgetUsdCap`) are per-cascade, not
+cumulative across cascades.
+
+## Interaction with Token Contract
+
+Token contract (`messaging.tokenContract: strict`) applies to every
+cascade subset. A cascade message that fails token resolution is
+persisted as pending (same as sample-level token failures) — not
+silently skipped.
+
+## Hard Rules
+
+- Generate Message cells do not always auto-cascade on late-passed rows —
+  Step 15 must explicitly queue newly-pending Generate Message cells.
+- Re-cascade iteration cap = 3. Trip escalates.
+- `messagesCount` flat + rubric graduating rows ⇒ re-cascade required.
+- Token contract enforcement applies per-cascade, not once-for-all.
+- Re-cascade NEVER re-runs `import_leads`, `check_rubric`, or
+  `enrich_with_prospeo`. Those are Step 13 / Step 14 actions.