@sellable/mcp 0.1.409 → 0.1.410

package/skills/refill-sends-workflow/SKILL.md

@@ -3,6 +3,9 @@ name: refill-sends-workflow
 description: Internal skill-led refill sends workflow for regular campaigns and evergreen campaigns.
 visibility: internal
 allowed-tools:
+  - mcp__sellable__list_senders
+  - mcp__sellable__get_sender_routing
+  - mcp__sellable__get_campaign_waterfall
   - mcp__sellable__resolve_campaign_fill_route
   - mcp__sellable__get_campaign_refill_state
   - mcp__sellable__fill_campaign_horizon
@@ -33,6 +36,7 @@ allowed-tools:
   - mcp__sellable__get_table_rows
   - mcp__sellable__get_campaign_table_schema
   - mcp__sellable__select_campaign_cells
+  - mcp__sellable__queue_campaign_cells
   - mcp__sellable__wait_for_campaign_processing
   - mcp__sellable__get_sender
 ---
@@ -48,15 +52,45 @@ prep, readiness, and evergreen primitives.
 Plain phrases that enter here include "fill", "refill sends", "max out sends",
 "load everyone up", and "fill horizon sends".
 
+Sender-scoped phrases include "refill senders", "fill senders", "max out
+senders", and "load everyone up". A sender-scoped request targets senders
+enrolled in active campaign-backed sequence campaigns, not one arbitrary active
+campaign.
+
 1. Call `resolve_campaign_fill_route` first. Use `intent:"plain"` for generic
    fill/load language, `intent:"active"` only when the user explicitly narrowed
    to active regular campaigns, and `intent:"evergreen"` only when the user
    explicitly asked for evergreen or horizon work.
-2. Pick exact ids from the resolver result. Do not use campaign names or table
-   names as target identifiers.
-3. Call `get_campaign_refill_state` for the selected `campaignId` or `tableId`.
-   This must be the next target-specific research primitive.
-4. Classify the target from refill state:
+2. Resolve sender context before choosing a target. Call `list_senders`; when a
+   managed program is involved, also call `get_campaign_waterfall`, and call
+   `get_sender_routing` when territory rules may constrain sender eligibility.
+   If the user named senders, map those names to exact sender ids. If the user
+   did not name senders and the request is sender-scoped:
+   - in `--yolo`, target all eligible healthy senders enrolled in active
+     campaign-backed sequence campaigns returned by the route/state evidence;
+   - outside `--yolo`, ask which eligible enrolled senders to refill before
+     choosing campaigns or mutating.
+   If the request is campaign-scoped or ambiguous "fill sends" language, infer
+   the relevant senders from the most recent scheduler-owned sends in
+   refill-state readbacks and report that inference.
+   Short form: `--yolo refill senders` means all eligible enrolled senders; non-yolo asks which enrolled senders.
+3. Read `get_campaign_refill_state` for candidate campaigns from the resolver
+   result. For a broad `active_campaigns` route, inspect enough candidates to
+   identify the campaign or small campaign set that most recently had
+   scheduler-owned sends for the relevant sender set. Do not stop after the
+   first resolver target unless it is also the most recent sender-relevant send
+   lane.
+   Short form: Do not stop after the first resolver target unless recent-send evidence supports it.
+   In `--yolo` sender-scoped mode, selecting every active campaign is still a
+   scope error, but selecting one best refill campaign per eligible sender is
+   expected. Pick the single highest-ranked recent-send or best-result campaign
+   for each target sender unless the refill-state evidence proves that a sender
+   already has enough ready/scheduled rows across enrolled campaigns or that a
+   different same-sender campaign is needed because the best lane is blocked.
+   Short form: `--yolo refill senders` selects all eligible enrolled senders, then the best campaign per sender.
+4. Pick exact ids from the selected refill-state response. Do not use campaign
+   names or table names as target identifiers for tool calls.
+5. Classify the target from refill state:
    - regular campaign: campaign-backed workflow table with normal source,
      sequence, senders, and send/refill stages.
    - evergreen campaign: managed always-on lane with current source evidence.
@@ -77,7 +111,10 @@ Use the refill-state response as the current facts receipt:
   approved, ready to schedule, scheduled;
 - active message prep job;
 - scheduler-owned scheduled counts by date/action from cells with non-null
-  `scheduledFor`;
+  `scheduledFor`; treat these as the last sends/continuation signal;
+- latest scheduled send date, latest scheduled-cell update when present,
+  sender overlap with the requested or inferred sender set, and whether future
+  scheduled sends already exist;
 - `freshness.stateHash` and exact campaign/table/workspace ids.
 
 Empty or unsafe states stop with the blocker: no fillable target, missing or deleted campaign,
@@ -89,9 +126,76 @@ scheduler, or unsupported direct campaign type.
 
 For regular campaign workspaces, rank regular campaigns from route and
 `get_campaign_refill_state` evidence. Choose the best existing refill target.
+The default campaign-scoped refill interpretation is "continue the campaign that
+was actually sending most recently for the relevant available senders", not
+"touch every active campaign". The default sender-scoped refill interpretation is
+"fill every eligible target sender from the best enrolled active campaign for
+that sender", not "fill only the first/best campaign globally".
+
+Default `--yolo` horizon is two send days when the user asks to fill, refill,
+load, or max sends without naming a different horizon. Send days are sender-local
+days with configured sending hours; do not treat weekends or other no-send-hour
+days as fillable capacity. If the user explicitly names a no-send calendar date,
+report that date as unschedulable and continue only for the next valid send day
+when the packet says "send days" or the user asked to max/refill senders broadly.
+
+For campaign-scoped requests, compute the target from the selected campaign's
+healthy sender daily capacity for the next two send days, minus already
+scheduler-owned future scheduled sends for those days and minus rows already
+ready to schedule. For sender-scoped requests, compute that gap per target sender
+across all active enrolled campaigns for that sender; count future scheduled
+cells and ready-to-schedule cells in any active enrolled campaign toward that
+sender's gap before preparing more rows. If ready/scheduled rows already cover a
+sender's gap, do not add rows or prep for that sender; report that the sender is
+loaded and awaiting the scheduler. If the gap is positive, prepare only the gap
+in the best same-sender campaign and keep all source-copy/prep caps tied to that
+two-day packet.
+Short form: default `--yolo refill senders` target is each eligible sender's two-send-day gap.
+
+Rank candidates in this order:
+
+1. **Sender match**: campaigns whose healthy sender ids match the user-named
+   senders, or the inferred sender set when the user said only "fill sends" or
+   "load senders". Do not include campaigns merely because they are active when
+   their sender set is unrelated.
+2. **Recent sends**: campaigns with the newest scheduler-owned scheduled counts
+   and non-null `scheduledFor` cells for those senders. Future scheduled sends
+   are stronger continuation evidence than old historical sends; otherwise use
+   the latest scheduled send date / newest scheduled-cell update from refill
+   state.
+3. **Continuation capacity**: campaigns with healthy senders, remaining daily
+   capacity, and a gap between current ready-to-schedule rows and the desired
+   sender capacity.
+4. **Same-campaign source health**: prefer campaigns whose current source has
+   enough `sourceAvailable` inventory to prepare the gap. If source inventory
+   is low or exhausted, choose same-campaign row replenishment before switching
+   campaigns.
+5. **Campaign scope**: keep the selected set small. For campaign-scoped
+   requests, normally choose one campaign. For sender-scoped requests, choose at
+   most one best campaign per target sender unless evidence shows one sender
+   needs multiple same-sender campaigns because the first is blocked or already
+   loaded.
+
 Do not create side campaigns, warm-post-engager side campaigns, on-demand campaigns,
 or unrelated campaigns as the default answer to a fill request.
 
+For each selected campaign, decide the next action by the smallest sufficient
+step:
+
+- **Enrich/prep more rows in the same campaign** when sender health is good,
+  recent sends point to this campaign, and `sourceAvailable` can cover the
+  ready-to-schedule gap.
+- **Add/import more rows to the same campaign/source path** when the campaign is
+  the right recent-send lane but source inventory or viable rows cannot cover
+  the gap.
+- **Use a different existing campaign** only when the recent-send/best-result
+  campaign for that sender is blocked, archived, missing sequence/source/senders,
+  disconnected, exhausted with no viable same-campaign replenishment path,
+  already loaded while the sender still has a gap, or the user explicitly asks
+  to move to another campaign.
+- **Ask what to create** only after resolver/state evidence shows there is no
+  suitable existing campaign for the requested sender set.
+
 When the best regular campaign is source-exhausted, recommend same-campaign source-ladder replenishment.
 Keep `selectedLeadListId` source identity distinct
 from the campaign `workflowTableId`.
@@ -109,6 +213,30 @@ Source replenishment choices:
   source prospects into the same campaign/source-list path, then confirm
   readiness.
 
+When reusing an existing source list on an already-large campaign, handle the
+campaign-table row cap automatically in `--yolo` mode. If `confirm_lead_list`
+fails with `USER_ADDED_ROWS_LIMIT_EXCEEDED`, parse `remainingRows`,
+`currentRows`, `requestedRows`, and `maxRows`; do not stop just because the full
+source list is too large. Instead, create a bounded same-source split:
+
+1. choose a split size no larger than `remainingRows`, the two-day refill row
+   budget, and the first-pass processing cap unless the packet named a higher
+   cap;
+2. read compact rows from the current `selectedLeadListId` with
+   `get_rows_minimal`;
+3. create a temporary bounded LinkedIn profile source list with
+   `load_csv_linkedin_leads`, preserving useful source columns such as post URL,
+   post author, engagement type/text, keyword, confidence, and why;
+4. call `confirm_lead_list` with that bounded source-list id, the same campaign
+   id, and `currentStep:"running"` for ACTIVE campaigns;
+5. verify the campaign table row count and review batch with
+   `get_campaign_table_schema` before any prep/approval.
+
+Do not use `add_on_demand_leads` or create an on-demand table as the automatic
+regular-campaign fallback. The fallback must stay same-campaign and
+source-list-backed.
+Short form: row-cap fallback means bounded same-source split, not stop or on-demand.
+
 ### Running Campaign Signal Discovery Recovery
 
 For an already-running regular campaign that needs same-campaign Signal
@@ -146,10 +274,10 @@ returns to Running after same-campaign source rows are copied. Do not call
 post-copy state transition.
 
 Before any source mutation, show exact approval evidence: workspace id,
-campaign id, workflow table id, source/provider id, source-list id when known,
-import caps, target dates/caps, dedupe/DNC/provider exclusion expectations, and
-expected row side effects. Then reread `get_campaign_refill_state`; if
-`freshness.stateHash` or exact ids changed, stop and ask for a fresh approval.
+campaign name, campaign id, workflow table id, source/provider id, source-list
+id when known, import caps, target dates/caps, dedupe/DNC/provider exclusion expectations, and expected row side effects. Present the campaign name and plain-English reason first; include ids only as proof and execution targets.
+Then reread `get_campaign_refill_state`; if `freshness.stateHash` or exact ids
+changed, stop and ask for a fresh approval.
 
 After source import, call `wait_for_lead_list_ready` and `confirm_lead_list`
 with the source-list id and campaign id. Imports append to the existing
@@ -179,18 +307,87 @@ Before prep or approval mutation, reread `get_campaign_refill_state` and compare
 If they changed, stop. A second concurrent refill run must see the first run's
 import/prep state on reread and avoid duplicate work.
 
+After the final reread and before the first mutating refill primitive, render
+one final approval packet in campaign-name-first language, then ask a
+host-native structured question with exactly two choices: `Accept` and
+`Decline`. The question is the execution boundary.
+Short form: exactly two choices: `Accept` and `Decline`.
+
+- In Codex interactive sessions, use `request_user_input`.
+- In Claude Code interactive sessions, use `AskUserQuestion`.
+- The question body must include this exact operator output packet shape before
+  the choices:
+  - workspace name/id and mode (`--yolo` or approval-required);
+  - sender scope, including selected sender names and skipped sender names with
+    health/enrollment reasons;
+  - a campaign-by-campaign plan table with campaign name, sender names, action,
+    target count/cap, source/list, and blocker/skip reason;
+  - exact workspace id, campaign id, workflow table id, source/action ids when
+    relevant, freshness/state hash, caps/dates, approval mode, and the next
+    MCP primitive to call;
+  - expected side effects, forbidden actions, and the stop/rollback condition.
+- The `Accept` choice must name the exact campaign, workspace id, campaign id,
+  workflow table id, source/action ids when relevant, caps/dates, approval mode,
+  expected side effects, and stop/rollback condition.
+- The `Decline` choice must stop with no mutation.
+- Do not proceed from a plain chat "ok", "yes", "go", or "do it" when the
+  structured question tool is available. If the structured question tool is not
+  available in an interactive session, stop and tell the user the quick question
+  panel is required for refill approvals. In non-interactive exec/automation,
+  print the approval packet and stop before mutation.
+
+`--yolo` mode is explicit auto-accept. If Christian includes `--yolo` in the
+same refill request, do not ask the `Accept` / `Decline` question. Instead:
+
+1. render the same final approval packet;
+2. reread `get_campaign_refill_state`;
+3. verify the route, workspace id, campaign id, table id, source/action ids,
+   caps/dates, approval mode, blockers, and side-effect class still match the
+   packet;
+4. execute only the exact packet.
+
+`--yolo` never authorizes launch/start, sending, archive/delete cleanup, raw
+scheduler writes, sender reassignment, unrelated campaigns, extra senders beyond
+the eligible sender set, or higher caps than the packet named. In sender-scoped
+`--yolo`, a bounded packet containing all eligible enrolled senders and at most
+one best campaign per sender is covered; arbitrary expanded campaign sets are
+not. If any state or scope drifts, stop and re-plan instead of auto-accepting the
+changed action.
+Short form: all eligible enrolled senders are covered by sender-scoped `--yolo`; arbitrary expanded campaign sets are not.
+Short form: direct scheduler writes are not covered by `--yolo`.
+Short form: stop and re-plan instead of auto-accepting the changed action.
+
 After same-campaign source copy, inspect the actual campaign-table position of
 the copied rows before starting prep. Newly copied rows often land after the first 100 table rows. Use `get_campaign_table_schema` to read the `reviewBatch`,
 then use `select_campaign_cells` diagnostics against
 `rowSelector:{ type:"reviewBatch" }` for `enrich`, `generateMessage`, and
 `approved` roles when needed.
 
+For bounded split refills, operate on the review batch first. Queue
+`queue_campaign_cells` for `columnRole:"enrich"` on
+`rowSelector:{ type:"reviewBatch" }`, wait for campaign processing, then queue
+`columnRole:"generateMessage"` for the same review batch or
+`needsGeneratedMessage` rows. If the bounded packet explicitly uses
+`approvalMode:"approve"` because the user asked to fill/schedule sends or
+provided `--yolo` for a two-day send fill, approve only the bounded review-batch
+cohort after current generated messages exist. Do not broad approve existing
+table rows.
+
 If review-batch enrich cells are pending or Generate Message cells are
 dependency-blocked, omit `maxRowsToCheck` so the adaptive prep job can cover the
 bounded table scan, or set a bounded cap high enough to include appended rows
 when row count evidence requires it. Do not run a fixed `maxRowsToCheck:100` prep pass after appending rows to a larger existing campaign table; it can spend
 the whole budget on older rows and miss the refill batch.
 
+Bound `targetPreparedMessages` to the actual ready-to-schedule gap for the
+selected campaign and sender set. In sender-scoped mode, compute and report the
+gap per sender. If ready/scheduled rows across active enrolled campaigns already
+cover a sender's gap, do not start prep for that sender; report that the sender
+is already loaded and awaiting the scheduler. If source inventory is available
+and the gap is small, prepare only the sender gap instead of filling every active
+campaign.
+Short form: prepare only the per-sender gap instead of filling every active campaign.
+
 Scheduled success requires a post-action reread proving scheduler-owned cells
 with non-null `scheduledFor`. Prepared, approved, and ready-to-schedule rows are
 intermediate states; report them as awaiting scheduler unless scheduled cells
@@ -225,9 +422,24 @@ the current source or ask for more research instead of walking the ladder.
 - No mutation in production unless Christian explicitly approves exact
   workspace, campaign/table ids, source/action ids, caps/dates, approval mode,
   expected side effects, and rollback/stop condition.
+- In interactive Codex or Claude Code, that explicit approval must be collected
+  through the host-native `Accept` / `Decline` question gate.
+- `--yolo` in the current refill request is explicit auto-accept for the
+  rendered bounded refill packet only; it does not loosen the launch/send,
+  scheduler-write, archive/delete, or drift rules above.
 
 ## Report
 
-Report the selected target, target type, source state, blockers, exact next
-primitive, approval required, and the freshness hash used. Say explicitly that
-nothing was launched and nothing was sent.
+Report in campaign-name-first language:
+
+- selected campaign name(s), target type, and sender names;
+- why they were selected, including last scheduled send date/future scheduled
+  send evidence and sender overlap;
+- whether the smallest next step is enrich/prep more in that campaign, add rows
+  to that campaign/source, use a different existing campaign, or ask what to
+  create;
+- source state, blockers, exact next primitive, approval required, and the
+  freshness hash used.
+
+Keep ids visible but secondary: show them under "Exact target" or "Proof", not
+as the main decision text. Say explicitly: nothing was launched and nothing was sent.