@sellable/mcp 0.1.793 → 0.1.794

package/dist/tools/registry.js

@@ -39,6 +39,11 @@ import { findLeadsProviderPreflightToolDefinitions } from "./provider-preflight.
 import { readinessToolDefinitions } from "./readiness.js";
 import { refillSendsToolDefinitions } from "./refill-sends.js";
 import { refillTargetPlanToolDefinitions } from "./refill-target-plan.js";
+import { refillV3AdvanceToolDefinitions } from "./refill-v3-advance.js";
+import { refillV3ContinueToolDefinitions } from "./refill-v3-continue.js";
+import { refillV3EditSelectedCampaignToolDefinitions } from "./refill-v3-edit-selected-campaign.js";
+import { refillV3FillReadyToolDefinitions } from "./refill-v3-fill-ready.js";
+import { refillV3WorldStateToolDefinitions } from "./refill-v3-world-state.js";
 import { refreshSenderEngagementToolDefinitions } from "./refresh-sender-engagement.js";
 import { rowToolDefinitions } from "./rows.js";
 import { rubricToolDefinitions } from "./rubrics.js";
@@ -63,6 +68,15 @@ export const allTools = [
     ...schedulerFillCapacityToolDefinitions,
     ...schedulerRunToolDefinitions,
     ...refillSendsToolDefinitions,
+    // Phase 146.5 Plan 08's TWO public Refill V3 surfaces: exactly one
+    // observation tool and exactly one bounded mutation tool.
+    ...refillV3WorldStateToolDefinitions,
+    ...refillV3FillReadyToolDefinitions,
+    ...refillV3EditSelectedCampaignToolDefinitions,
+    // Phase 146.5 Plan 10: the one deterministic coordinator. It completes the
+    // final public V3 catalogue of exactly four tools.
+    ...refillV3AdvanceToolDefinitions,
+    ...refillV3ContinueToolDefinitions,
     ...setupEvergreenCampaignsToolDefinitions,
     ...campaignHorizonFillToolDefinitions,
     ...campaignMessagePreparationToolDefinitions,
@@ -119,6 +133,11 @@ export const allTools = [
 /** Closed public surface used by the paired MCP/installer asset inventory. */
 export const refillProjectionToolNames = [
     "refill_sends",
+    "refill_v3_world_state",
+    "refill_v3_fill_ready",
+    "refill_v3_edit_selected_campaign",
+    "refill_v3_advance",
+    "refill_v3_continue",
     "get_refill_target_plan",
     "get_campaign_refill_state",
     "start_campaign_message_preparation",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/mcp",
-  "version": "0.1.793",
+  "version": "0.1.794",
   "type": "module",
   "description": "Sellable MCP server for Claude Code, Codex, and Hermes campaign workflows",
   "main": "dist/index.js",

package/skills/refill-sends/SKILL.md

@@ -4,6 +4,8 @@ description: Refill projected sends across a workspace or selected senders throu
 visibility: public
 allowed-tools:
   - mcp__sellable__refill_sends
+  - mcp__sellable__refill_v3_advance
+  - mcp__sellable__refill_v3_continue
   - mcp__sellable__get_refill_target_plan
   - mcp__sellable__get_scheduler_fill_capacity
   - mcp__sellable__get_subskill_asset
@@ -21,17 +23,43 @@ allowed-tools:
 # Refill Sends
 
 Use this skill for “fill”, “refill sends”, “max out sends”, “load everyone up”,
-or “fill horizon sends”. `refill_sends` is the only execution owner. The host
-resolves the request, invokes the coordinator, and follows its exact
-continuation; it never reconstructs the refill ladder from low-level tools.
+or “fill horizon sends”. Exactly one coordinator owns execution: `refill_v3_advance`
+on the V3 route, `refill_sends` on the V1 route. The host resolves the request,
+invokes that coordinator, and follows its exact continuation; it never
+reconstructs the refill ladder from low-level tools.
 
 Host commands:
 
 - Claude Code: `/sellable:refill-sends`
 - Codex: `$sellable:refill-sends`
 
+## Route selection — do this FIRST
+
+Decide the route before parsing scope, before loading any flow asset, and before
+any tool call other than auth/workspace resolution. The predicate is
+MECHANICAL and observable in the connected Sellable MCP tool list:
+
+> **Is `refill_v3_advance` one of the tools this server exposes?**
+
+- **Yes → take the Refill V3 route.** This is the default for every workspace on
+  a server that exposes the tool. Go to [Refill V3](#refill-v3) and follow it;
+  the V1 ladder in the rest of this document does not apply.
+- **No → take the V1 route.** The installed server predates Refill V3, so
+  `refill_sends` is the only coordinator available. Follow this document from
+  [Entry and exact scope](#entry-and-exact-scope) onward.
+
+Never infer the route from a workspace flag, a campaign field, a tool result, or
+the operator's wording: no such cutover signal exists, and guessing at one is
+what makes an ordinary refill request silently take the wrong route. Report the
+selected route explicitly before the first coordinator call.
+
 ## Entry and exact scope
 
+Everything from here down to [Refill V3](#refill-v3) is the **V1 route**. Skip it
+entirely when route selection chose V3. On this route `refill_sends` is the only
+execution owner and the host follows its exact continuation; it never
+reconstructs the refill ladder from low-level tools.
+
 Accepted request fields are `--yolo`, `workspaceId`, `--sender`/`senderIds`/
 `senderNames`, `actionTypes`, `--until`/`untilDate`, `--target-date`/
 `targetDate`, and compatibility `horizonSendDays`. Omitted dates mean the
@@ -55,7 +83,9 @@ flowchart TD
     SENDERS --> SG{"Every selector resolves exactly?"}
     SG -- No --> SB["Output: blocked_retryable / sender_selector_unresolved with candidates"]
     SG -- Yes --> DATE["Normalize 48h, exact targetDate, or inclusive untilDate in sender-local time"]
-    DATE --> D1["D1: call get_refill_target_plan read-only with exact scope"]
+    DATE --> ROUTE{"Does this server expose refill_v3_advance?"}
+    ROUTE -- Yes --> V3["Refill V3 route: load core/flow.v3.json and call refill_v3_advance"]
+    ROUTE -- No --> D1["D1: call get_refill_target_plan read-only with exact scope"]
     D1 --> RENDER["Render sender/campaign waterfall, coverage ledger, first action, side effects, forbidden actions, and stop condition"]
     RENDER --> D2["D2: call refill_sends with workspaceCoordinator true plus displayed targetShapeRevision and actionKey"]
 ```
@@ -551,3 +581,58 @@ available work.
   sweep/status, and bounded receipts. Never use individual cell ids, Prisma,
   SQL, direct database access, or production-environment scripts as completion
   proof. Redact raw copy and prospect fields.
+
+## Refill V3
+
+This is the DEFAULT route whenever `refill_v3_advance` is exposed (see
+[Route selection](#route-selection--do-this-first)). `refill_v3_advance` is then
+the only execution owner and `refill-sends-workflow` plus its `core/flow.v3.json`
+asset is the contract to load — load the prompt and that asset, verify the `v3`
+compatible range, and report the version before the first call. Call
+`refill_v3_advance` with `{workspaceId, scope}` — plus `yolo: true` only when the
+operator asked for `--yolo` — and call it again after each `advanced` or
+`campaign_attention_required` result until it answers `awaiting_external_change`,
+`complete`, or `blocked`.
+
+Resolve the workspace BEFORE the first call, exactly as the V1 route already
+requires. `workspaceId` must be an exact id on every automation call: when the
+operator names a workspace, call `list_workspaces` first and match that name to
+its id, and use the configured or active workspace only when the operator named
+none. If nothing accessible matches the name, or more than one does, stop and say
+so — do not fall back to the configured workspace — and never change the shared
+active workspace to steer an automation.
+
+Map the rest of the request onto those keys and nothing else: the sender/date
+envelope becomes `scope` (a 1-3 day `sender_local_horizon`, or
+`exact_sender_dates` when the operator named exact senders or dates). There is no
+mode: WHICH campaign may be started is DERIVED from the workspace's own
+campaigns and can never be requested.
+
+`--yolo` still means what it has always meant, and it is the ONE remaining
+execution input. It is the operator's AUTONOMY GRANT, read from their words
+alone, and it decides two things together:
+
+- **Granted** (`yolo: true` on every call of that run): after a row's active
+  campaigns are exhausted, one derived-evergreen start-eligible campaign may be
+  started, and you receive it as an ordinary executed `start_evergreen_campaign`
+  action. Keep calling advance until a terminal without checking back.
+- **Withheld** (omit the key): no paused campaign is started — the backend
+  refuses it and answers the exhaustion terminal instead — and you surface each
+  result and ASK before calling advance again.
+
+Never infer the grant from a workspace flag, a campaign field, a tool result, an
+idle-looking workspace, or a previous terminal, and never set it to make a run
+finish. Pass no other execution flag and no mode, and do not call
+`get_refill_target_plan`, `refill_sends`, or any placement, scheduler, source, or
+send tool on this route.
+
+An `advanced` result is ALREADY EXECUTED: surface its action identity, receipt,
+and replacement observation, and never run the action or call its authority again.
+Only `campaign_attention_required` needs you — route its one selected campaign to
+`refill-sends-work-campaign` and return the chosen action through
+`refill_v3_continue`, which first revalidates the packet against fresh world
+state and then executes at most one existing authority.
+
+This skill chooses no sender, date, lane, campaign, or action, holds no counter or
+cursor between calls, and declares no terminal, exhaustion verdict, or health
+classification of its own. V1 `refill_sends` behavior is unchanged.

package/skills/refill-sends-waterfall-order/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: refill-sends-waterfall-order
+description: Order up to three already-issued campaigns for ONE sender and lane, with a rationale each, and optionally propose activating one paused campaign.
+visibility: internal
+allowed-tools:
+  - mcp__sellable__get_campaign
+---
+
+# Refill Sends · Waterfall Order
+
+You are given ONE sender, ONE lane, and the complete set of campaigns the backend
+already issued for that row. Decide the ORDER in which those campaigns should be
+worked, and say why.
+
+By default you call no tools. You mutate nothing, ever. Your whole output is a
+small JSON object that a deterministic validator checks against
+`REFILL_V3_WATERFALL_PROPOSAL_SCHEMA` before anything happens.
+
+ONE bounded read is allowed: the sellable `get_campaign` tool (the campaign
+brief). Use it ONLY when the evidence lines in your input are insufficient to
+order confidently — at most ONE read per candidate campaign, by its
+`campaignId`. When a brief was consulted, the rationale MUST say so and state
+what the brief changed about the ordering. An ordering you could make from the
+evidence lines alone never spends a read.
+
+## What you are given
+
+- `sender` — the exact sender for this row;
+- `lane` — the exact lane being filled;
+- `activeCampaigns[]` — every campaign the backend issued for this row, each
+  carrying its `campaignId`, its transport effectiveness evidence, recent-use
+  evidence, and its count of eligible rows for this lane;
+- `inactiveCampaigns[]` — PAUSED campaigns the backend has already confirmed are
+  start-eligible;
+- `availableSlots` — how many actions this row can still take today;
+- `guidance` — OPTIONAL and absent by default. When present it may carry a
+  history of prior choices (`priorChoices`), why one experiment takes precedence
+  (`experimentPrecedence`), or an operator-preferred campaign
+  (`operatorPreferredCampaignId`). Weigh it in your rationale. It introduces no
+  new database model, and durable managed-waterfall storage stays out of scope.
+
+If you feel you need context that neither the input nor a bounded brief read
+carries, say so in your rationale. That is a data-effectiveness gap in the
+observer's campaign facts to be fixed at its source; it is never a reason to
+reach for any other tool.
+
+## Ordering precedence
+
+Work through these layers IN ORDER. Every rationale names which layer(s) it
+used.
+
+### 1. Continuity exploration first
+
+Before ordering anything, read what was recently ON for this sender and lane:
+each candidate's recent-use evidence (`lastActualUse` on its evidence lines)
+and, when present, `guidance.priorChoices`. Continuity is first-class: a
+recently-worked campaign with remaining supply keeps momentum by default.
+Reordering away from the most recently used campaign requires a stated reason
+in its rationale.
+
+### 2. Operator guidance
+
+When `guidance` is present it wins, and the rationale cites it —
+`operatorPreferredCampaignId`, `experimentPrecedence`, and the history in
+`priorChoices`.
+
+### 3. The evergreen-family ladder
+
+Some workspaces run the standing evergreen families instead of bespoke
+campaigns. You recognize them by the candidates' lead-source families — never
+by a workspace flag: post-engager campaigns, signal-discovery campaigns, and a
+cold fallback together form the evergreen ladder.
+
+When the candidates show evergreen families, the canonical waterfall order is
+`post_engager → signal_discovery → cold`: post engagers already touched the
+sender's content, signal discovery found a live buying signal, and cold is the
+fallback.
+
+The family semantics are strict: post-engager campaigns are engagers of the
+sender's own content — that is the warm relationship. Campaigns tracking
+other people's posts (thought leaders, third parties) belong to
+signal_discovery, however they are named. When the evidence lines leave this
+unclear, the bounded `get_campaign` brief read may inform the judgment. The family reply-rate benchmarks below are the quantitative WHY —
+warmest source, highest expected reply. Deviate only when the evidence lines
+argue for it, and say why in the rationale either way. The deterministic gates
+stay sovereign: issued-set membership, start-eligibility, and shape are still
+checked after you, and the three-campaign bound is unchanged.
+
+### 4. Bespoke campaigns: performance first, supply-gated
+
+Otherwise, order by the BEST-PERFORMING campaigns — use the transport
+effectiveness and recent-use evidence, the family benchmarks below, and any
+live `familyBenchmarks` data — GATED by supply adequacy. A campaign without
+enough eligible rows for the lane being filled, measured against this row's
+`availableSlots`, does not lead the waterfall however well it performed.
+
+Performance first; the supply gate second. This is guidance for your judgment,
+not a deterministic formula: the validator checks only issued-set membership,
+start-eligibility, and shape, so the ordering decision is genuinely yours.
+
+## Family reply-rate benchmarks (priors + live data)
+
+Typical benchmarks by lead-source family — actual campaign/workspace data
+supersedes when present:
+
+- `post_engager` — HIGH, sometimes ~40% reply: they already engaged the
+  sender's content;
+- `signal_discovery` — 10–20% reply: a live buying signal;
+- `cold` — ~5–7% reply: no prior touch.
+
+When the input carries live `familyBenchmarks` (this workspace's own
+per-family engagement aggregates, e.g.
+`post_engager no data · signal_discovery 12% reply n=340 · cold 3% reply n=2100`),
+the REAL data leads and these priors only fill the cold start. A family shown
+with no data has no fact — never treat that as a zero rate. Small samples ride
+with their `n`, so weigh them accordingly, and say WHICH layer the rationale
+used: workspace family data or the benchmark prior.
+
+### Empty does not mean dead — the refresh candidate
+
+An evergreen-family campaign — especially a post-engager campaign — with zero
+current rows is a REFRESH CANDIDATE, not a dead entry. Its sources keep
+producing: new people engage the tracked posts, new signal rows arrive. Its
+work is therefore a SOURCE REFRESH. Rank it by the ladder as usual, and state
+explicitly in its rationale that its work is a source refresh to look for new
+rows. Never drop it from the order merely because its current row count is
+zero.
+
+## Optional activation
+
+You MAY propose activating exactly ONE campaign from `inactiveCampaigns[]`. It is
+legal only for a campaign that is present in that issued set. Activation runs
+through the existing campaign mutation authority, is followed immediately by a
+two-lane re-observation, and is bounded to one activation per row per task.
+
+Propose an activation only when the active set genuinely cannot fill the lane and
+the paused campaign is a better use of the row than leaving slots empty. Say
+which of those two things is true in the rationale.
+
+## Output shape
+
+```json
+{
+  "order": [{ "campaignId": "...", "rationale": "..." }],
+  "activation": { "campaignId": "...", "rationale": "..." }
+}
+```
+
+- `order` carries between one and three campaigns;
+- every campaign id must already be in `activeCampaigns[]` for THIS row — a
+  campaign the backend did not issue can never enter, and naming one is rejected;
+- every entry needs a non-empty `rationale`. An unexplained order is unauditable
+  and cannot be A/B compared, so a missing rationale is rejected;
+- `activation` is optional and, when present, names exactly one campaign from
+  `inactiveCampaigns[]`;
+- no other field is accepted.
+
+## Hard limits
+
+Each of these is a typed rejection, and the row then continues on the
+deterministic fallback order rather than stopping:
+
+- a campaign absent from the issued active set;
+- the same campaign twice, including once ordered and once activated;
+- an empty order;
+- an order longer than three;
+- more than one activation;
+- an activation for a campaign absent from the issued inactive set, or one that
+  is not start-eligible;
+- any output that is not exactly the object above.
+
+Never guess a campaign id. Never invent effectiveness evidence, a slot count, or
+an eligibility fact. Never propose starting, pausing, editing, or scheduling
+anything: ordering and one bounded activation are the only decisions you own.

package/skills/refill-sends-work-campaign/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: refill-sends-work-campaign
+description: Judge why ONE already-selected refill campaign is dry and choose exactly one repair action from a closed vocabulary.
+visibility: internal
+allowed-tools:
+  - mcp__sellable__get_provider_prompt
+---
+
+# Refill Sends · Work One Selected Campaign
+
+You are handed ONE campaign that a deterministic selector already chose. Your
+whole job is to read the bounded evidence you were given, decide **why this
+campaign is dry**, and return **exactly one action** from the closed list below.
+
+**You never mutate anything.** You do not write to the database, you do not send,
+you do not schedule, you do not start or pause a campaign, and you do not call a
+mutation tool. You return one action; a deterministic authority validates it,
+executes it through its existing owner, returns a before/after receipt, and then
+forces a fresh two-lane observation. That authority is the only thing that
+changes product state, and it will refuse anything you invent.
+
+## What you are given, and what you may read
+
+Your input packet carries exactly this and nothing more:
+
+- the selected `workspaceId`, `campaignId`, `tableId`, `campaignVersion`,
+  `evidenceFingerprint`, `senderId`, and `date`;
+- the campaign's type, objective, protected-fit digest, current lead-source
+  family and provider;
+- saved source lineage, the prior yield receipt, and the searched-negative-set
+  fingerprints;
+- the deterministic remaining gap, the four supply counts, the live `activeJob`
+  (or `null`), a failed-job reference (or `null`); and
+- the bounded diagnostic counts and references needed to choose one action.
+
+You choose the action only. The deterministic continuation loads the exact
+diagnostic cohort of at most 10 rows, preserves table order across enriched
+islands, selects the row ids, applies the batch cap, and validates current
+failure evidence. Do not call a selector merely to discover batch ids and do
+not invent a prefix, offset, range, or row id. Return
+`consumedDiagnosticRowIds: null`; the backend owns the batch.
+
+You may not search the workspace, list campaigns, look at another campaign,
+another sender, another lane, or another date.
+
+## The closed action vocabulary
+
+Return exactly ONE of these. The list is generated from
+`REFILL_V3_CAMPAIGN_ATTENTION_ACTIONS` and is the complete set of things you are
+allowed to decide. There is no other action, no combination, and no "none of the
+above except this one thing I thought of".
+
+<!-- BEGIN GENERATED FROM REFILL_V3_CAMPAIGN_ATTENTION_ACTIONS -->
+
+1. `rerun_errored_cells`
+   Choose when: the packet reports repairable current errors or a currently
+   supported failed-job reference. The continuation resolves and validates the
+   exact failed rows.
+
+2. `repair_campaign_config`
+   Choose when: a specific allowlisted configuration field is malformed in a way
+   the evidence shows, and correcting that one field unblocks the existing rows.
+   Name the field and the corrected value. Never the campaign name, brief,
+   positioning, senders, current step, interaction mode, or template meaning.
+
+3. `enrich_bounded_sample`
+   Choose when: `diagnosticRowRef.selectorRef` is
+   `needsEnrichment:actionable:v1` AND `diagnosticRowRef.count > 0`. This exact
+   selector-owned count outranks every rubric, source, and exhaustion decision.
+   `supply.needsEnrichment` is the broader campaign-builder chip and may include
+   zero-cell orphans, permanent bad identities, external credit/quota waits, and
+   retry-terminal rows; never choose enrichment from that broad number alone. A
+   rubric verdict over an actually executable unenriched row is **invalid**,
+   because the fields the rubric reads do not exist yet, so it is
+   always a false negative. Never judge fit, relax a rubric, or broaden a source
+   while the exact actionable selector still reports enrichment work.
+
+4. `regenerate_stale_messages`
+   Choose when: `readyForMessageGeneration > 0` and specific rows have missing,
+   failed, or stale generated messages AND the approved template's meaning is
+   unchanged. The continuation resolves the exact `needsGeneratedMessage`
+   cohort. Set `templateMeaningChanged: false`. Copy only the exact
+   `templateFingerprint` supplied by the packet; otherwise return
+   `templateFingerprint: null`. Never rename that field or invent a fingerprint.
+   If the template or sequence meaning would change at all, set
+   `templateMeaningChanged: true` and expect the iteration to exit to the
+   separate approval boundary. You may not smuggle a meaning change through
+   repair, source work, or rubric relaxation.
+
+5. `patch_filter_criteria`
+   Choose when: the campaign's filter criteria demonstrably exclude the ICP the
+   objective describes, and one field-level relaxation fixes it. The patch must
+   preserve the approved objective and every employment, DNC, legal, and explicit
+   exclusion invariant. A value that weakens any protected invariant is invalid.
+
+6. `patch_source_criteria`
+   Choose when: the saved source criteria are wrong for this campaign's objective
+   and one field-level correction fixes it, with the same protected invariants
+   preserved.
+
+7. `broaden_source_family`
+   Choose when: the existing rows are healthy and enriched, supply is genuinely
+   short of the deterministic remaining gap, and a materially different, prompt-
+   compliant search is available. You choose the family, the query, and the
+   minimal filter delta. See "Choosing a source action" below.
+
+8. `request_rubric_trial`
+   Choose when: NOTHING above applies. This is the strict last resort. The
+   bounded sample must be enriched, its rubric verdicts must genuinely fail on
+   real enrichment evidence, and the campaign objective and protected exclusions
+   must stay intact. If any repair, regeneration, or untried prompt-compliant
+   source action remains, choose that instead — the authority will refuse a
+   rubric trial that jumps the queue.
+
+9. `await_active_job`
+   Choose when: `activeJob` is non-null for any kind and any status. This is the
+   only legal action while a job is live. You get finite wait guidance plus a
+   re-observation requirement, never an open-ended block. Do not queue a second
+   job, and do not "help" by doing something else in the meantime.
+
+10. `record_source_frontier_exhausted`
+    Choose when: fresh bounded evidence shows that no prompt-compliant broadening
+    remains. Supply a complete `exhaustionEvidence` block. A deterministic
+    predicate will falsify your claim against live counts, live jobs, scan
+    termination type, and untried broadenings; if any of those contradicts you,
+    the claim is refused and the flow continues. A single empty or below-floor
+    round is **never** exhaustion.
+
+<!-- END GENERATED FROM REFILL_V3_CAMPAIGN_ATTENTION_ACTIONS -->
+
+## Escalation order
+
+Work the list top-down and take the FIRST action whose criterion is satisfied:
+
+- a live job wins over everything: wait, bounded, and re-observe;
+- then an exact failure to rerun, or a malformed allowlisted config field;
+- then **exact actionable enrichment, before any rubric judgement**;
+- then exact same-meaning generation of missing, stale, or failed messages;
+- then a filter or source criteria correction;
+- then a contextual source-family, query, or filter broadening;
+- then a rubric trial, strictly last;
+- and only on complete fresh evidence, an exhaustion record.
+
+## Choosing a source action
+
+Before an action that starts a NEW provider search, or records provider-frontier
+exhaustion, select ONE active provider and load exactly its guidance with
+`get_provider_prompt({ provider, campaignOfferId })` using the selected
+campaign's id. Load exactly one. Never preload guidance for a provider you did
+not select, and never load any guidance at all when you are only draining supply
+that is already imported into the campaign table, or continuing a non-provider
+post-engager source. Name what you loaded in `providerPromptRef`.
+
+Make ONE minimal, campaign-aligned search delta. Preserve the campaign
+objective, the required fit constraints, the exclusions, DNC, and compliance.
+Your `requestFingerprint` must be materially different from every fingerprint in
+the searched negative set: a timestamp change, a counter, a reordered but
+equivalent filter list, or a whitespace edit is not a material difference and
+will be refused as a replay.
+
+For a signal-discovery posts search:
+
+- derive exactly 5 keywords per round, aligned to the loaded provider guidance
+  and adjacent to the campaign's proven existing keywords;
+- select AT MOST 5 candidate posts from that round's results;
+- pick the BEST posts in this order: (1) expected ICP fit of the post's engagers,
+  (2) engagement volume high enough that scraping is efficient — qualified
+  prospects per scrape, not breadth for its own sake, (3) recency. Fall back to
+  lower-engagement or less-ideal posts only when better candidates are
+  unavailable or already exhausted within the round;
+- record a per-post `expectedYieldBasis` for every post you select. A pick with
+  no recorded basis is refused, and a bad pick is caught by the deterministic
+  yield floor afterwards — the rationale is what makes it diagnosable.
+
+When you evaluate sampled candidates for quality, record a per-candidate verdict
+with the candidate identity, `pass` or `fail`, and the rubric basis. You judge
+which candidates pass. The deterministic evaluator owns the sample size, the
+arithmetic, the comparison against the floor, and the routing decision.
+
+## What is NOT yours
+
+These are computed for you and must be consumed, never reproduced:
+
+- queue order and campaign selection;
+- provider availability;
+- any yield, gap, threshold, or cap number;
+- hard filter bounds;
+- receipt novelty and replay identity;
+- rubric safety limits;
+- message eligibility;
+- cohort size and batching. When the sample is healthy, sizing and batching are
+  delegated to the existing adaptive preparation worker. Supply no batch size, no
+  row count, no limit, no offset, and no retry counter. If you name one, the
+  iteration is refused before any dependency is touched.
+
+Connection health is not yours either. If you can see that a sender is
+disconnected, is missing credits, is connecting, or needs a credential or paid
+credit recheck, do not touch config, filters, source criteria, rubrics, or
+messages to work around it. That evidence belongs to a different owner and it
+will be intercepted before you are invoked.
+
+## When the evidence is insufficient
+
+The coordinator issues this seam only when its fresh facts support at least one
+closed action. If the packet contradicts that invariant, stop and report the
+packet defect; do not fabricate a continuation decision. Never guess a
+fingerprint, provider, filter value, count, or job id, and never widen scope.
+
+## Output shape
+
+Return one JSON object:
+
+```json
+{
+  "scopeEcho": {
+    "campaignId": "...",
+    "tableId": "...",
+    "campaignVersion": 0,
+    "evidenceFingerprint": "..."
+  },
+  "actions": [
+    {
+      "action": "...",
+      "rationale": "...",
+      "rowIds": null,
+      "sourceCommand": null,
+      "candidateVerdicts": null,
+      "templateFingerprint": null,
+      "templateMeaningChanged": false,
+      "exhaustionEvidence": null,
+      "providerPromptRef": null
+    }
+  ],
+  "consumedDiagnosticRowIds": null
+}
+```
+
+`actions` must contain **exactly one** entry. Zero entries, two entries, and the
+same entry twice are each a distinct closed failure, and none of them produces a
+fallback effect. Every entry needs a non-empty `rationale`; an unexplained
+decision is unauditable and is refused. The action object accepts exactly the
+keys shown above; never add a synonym or a guessed field.
+
+## After the action
+
+The authority returns a receipt with exact before/after fingerprints, the changed
+fields, an effect key, and rollback data, and then a fresh exact sender/date
+two-lane observation runs. That is the end of your iteration.
+
+A **second mutation** from the same evidence packet is forbidden. If more work
+remains, it happens in a later iteration, against the fresh observation. Do not
+chain, do not retry the same action, and do not repeat a search whose fingerprint
+you already used.