@sellable/mcp 0.1.512 → 0.1.514

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

@@ -0,0 +1,138 @@
+---
+name: refill-sends-v2-workflow
+description: Internal execution workflow for refill sends v2 fenced runs.
+visibility: internal
+allowed-tools:
+  - mcp__sellable__refill_sends_v2
+  - mcp__sellable__get_refill_plan_v2
+  - mcp__sellable__get_subskill_prompt
+  - mcp__sellable__get_subskill_asset
+  - mcp__sellable__get_auth_status
+  - mcp__sellable__get_active_workspace
+  - mcp__sellable__list_workspaces
+  - mcp__sellable__get_workspace
+---
+
+# Refill Sends V2 Workflow
+
+This internal workflow mirrors the run-record gates enforced by
+`refill_sends_v2`: bootstrap, plan, execute, verify, and report. Dry runs stay
+read-only. Real runs execute only packet-named bounded work under a fenced run
+lease and return terminal, blocked, or in-progress results.
+
+Runtime flow asset: after loading this prompt, load
+`get_subskill_asset({ subskillName: "refill-sends-v2-workflow", assetPath: "core/flow.v1.json" })`
+through MCP, continue chunks until `hasMore:false`, parse the JSON, and verify
+`workflow:"refill-sends-v2-workflow"` with a `v1` version before driving the
+loop. If the asset cannot load or parse, stop with
+`blocked:refill_sends_v2_workflow_asset_unavailable`; do not emulate it from
+local files or memory.
+
+## G0 Bootstrap
+
+Resolve request-scoped `workspaceId` using read-only auth and workspace tools.
+Scheduled or autonomous runs must not rely on implicit workspace state.
+
+Start or resume the execution loop:
+
+```text
+refill_sends_v2({ workspaceId, intent:"auto", senderIds?, approvalMode?, runId?, fence? })
+```
+
+Use `dryRun:true` only when the user asked for read-only inspection. A dry run
+writes a journal only. A real run creates or resumes a run record, refreshes
+paid-credit trust only when packet facts require it, and returns a resume handle
+when the current invocation must pause.
+
+## G1 Plan
+
+The loop reads `get_refill_plan_v2` with runState fed back from the run record.
+It captures `planRevision`, `stateRevision`, and `targetShapeRevision`, then
+validates the packet before dispatch. Packet coherence is required: fingerprint
+shape, tool input completeness, lane-chain membership, census-vs-rung
+consistency, and terminal/action exclusivity. An incoherent packet is replanned
+once, then blocked as `packet_incoherent`.
+
+The packet's `supplyCensus`, `censusReason`, and `pipelineDiagnosis` checklist
+are the reason for the next rung. Repair is replan-driven: the planner names
+the repair rung, such as re-run errored enrichment/message cells
+(`rerun_errored_cells`), approve generated messages that are ready for review
+(`approve_messages`), or start the paused campaign so ready rows can schedule
+(`start_campaign`). The loop bounds and refuses repair loops; it never invents
+a fix list.
+
+Use plain-language labels first and tokens second, for example "copy leads
+already found into the campaign table (`reconcile_source_copy`)".
+
+## G2 Execute
+
+The loop executes only the packet head action whose fingerprint was captured at
+G1. Stale packets are refused and replanned.
+
+Allowed packet-named work:
+
+1. start the paused campaign so ready rows can schedule (`start_campaign`) when
+   the campaign is in the pinned lane chain;
+2. approve generated messages that are ready for review (`approve_messages`);
+3. enrich the next batch of unenriched rows (`enrich_more`);
+4. copy leads already found into the campaign table (`reconcile_source_copy`);
+5. re-run errored enrichment/message cells (`rerun_errored_cells`);
+6. find more leads via this campaign's original source
+   (`add_leads_same_source`) for mechanical same-source continuations;
+7. wait for the scheduler to pick up ready rows (`wait_for_scheduler`).
+
+Never create campaigns, switch providers, lower thresholds, write scheduler
+fields, send/archive/delete, or mutate brief/filter/message/sequence/sender
+config inside refill.
+
+Sales Nav and Prospeo continuations that need human source work are blocked as
+scoped handoffs:
+
+```text
+$sellable:create-campaign [campaignId]
+```
+
+The handoff scope is source work only: same saved-search identity, import mode
+`add` into the same source list, no new campaign, no provider-family switch, and
+no brief/rubric/message/sequence/sender changes without a separate approval
+packet.
+
+## G3 Verify
+
+Verification is whole-row and bounded. The loop records planned -> did ->
+outcome, then verifies before replanning.
+
+- Own active prep jobs are reattached by `requestSource` and `requestHash`; do
+  not re-dispatch prep while the job is active.
+- Foreign prep jobs are waited out or blocked as `foreign_prep_active`; their
+  outcomes are not adopted.
+- Active enrichment/import work is handled by bounded packet rereads.
+- The conversion verdict after the first prep batch is journaled from packet
+  facts. The plan gate withholds a second unproven prep batch when
+  `censusReason` is `conversion_blocked`.
+- Honest rubric failure means a human updates the rubric or changes lead source.
+- Capped scheduler capacity is complete.
+
+Scheduler wait is cross-invocation. If the tool returns `in_progress` with
+sweep guidance, re-invoke `refill_sends_v2` with `{runId, fence}`. The scheduler
+budget is cumulative at the run level. Zero pickup after a confirmed sweep is
+debugged from `pipelineDiagnosis`; it is not waited out forever.
+
+## G4 Report
+
+Completion proof is the run record at `g4_terminal` with a named doneReason and
+journal evidence showing planned -> did -> outcome plus a terminal block and
+index line. A plan packet alone is not completion proof.
+
+Terminal reasons are `complete`, `capped_by_scheduler`,
+`loaded_awaiting_scheduler`, `lanes_exhausted`, `blocked`,
+`no_refillable_campaigns`, and `not_an_evergreen_workspace`.
+
+`loaded_awaiting_scheduler` remains the run-record token, but report copy must
+include remaining-ready count, exact expected pickup time, and the resume
+handle. Do not render bare "loaded, awaiting scheduler" as a final answer.
+
+Report campaign names and sender names first, ids second. Include lane source,
+lane chain, chosen label with token secondary, plan revision, terminal reason or
+resume handle, journal path, blocked continuation packets, and firstFailing
+checklist when present.

package/skills/refill-sends-v2-workflow/core/flow.v1.json

@@ -0,0 +1,372 @@
+{
+  "version": "v1.0",
+  "workflow": "refill-sends-v2-workflow",
+  "principle": "Execute refill sends v2 through a fenced run record: bootstrap, plan, execute, verify, and report. Dry runs stay read-only; real runs execute only packet-named bounded work.",
+  "laneSources": [
+    "managed_waterfall",
+    "dashboard_evergreen",
+    "active_campaign"
+  ],
+  "terminalReasons": [
+    "complete",
+    "capped_by_scheduler",
+    "loaded_awaiting_scheduler",
+    "lanes_exhausted",
+    "blocked",
+    "no_refillable_campaigns",
+    "not_an_evergreen_workspace"
+  ],
+  "blockers": ["workspace_access"],
+  "enumeratedRungs": [
+    "start_campaign",
+    "approve_messages",
+    "wait_for_active_work",
+    "enrich_more",
+    "reconcile_source_copy",
+    "rerun_errored_cells",
+    "add_leads_same_source",
+    "paid_lane_fallback",
+    "next_campaign",
+    "wait_for_scheduler",
+    "done"
+  ],
+  "rungLabels": {
+    "start_campaign": "start the paused campaign so ready rows can schedule",
+    "approve_messages": "approve generated messages that are ready for review",
+    "wait_for_active_work": "wait for active campaign work to finish",
+    "enrich_more": "enrich the next batch of unenriched rows",
+    "reconcile_source_copy": "copy leads already found into the campaign table",
+    "add_leads_same_source": "find more leads via this campaign's original source",
+    "paid_lane_fallback": "move paid InMail demand to the connection fallback lane",
+    "next_campaign": "move to the next campaign in the lane",
+    "wait_for_scheduler": "wait for the scheduler to pick up ready rows",
+    "done": "finish the refill run",
+    "rerun_errored_cells": "re-run errored enrichment/message cells"
+  },
+  "hardRules": [
+    "dry-runs write journals only and never create run records",
+    "execute only the packet fingerprint captured at the last plan gate",
+    "validate packet coherence before dispatch; replan once, then block packet_incoherent",
+    "repair rungs come from the plan packet; the loop bounds and refuses, never self-emits repair actions",
+    "capped_by_scheduler is complete, never poll",
+    "awaiting scheduler is not an end state; window-closed reports name remaining-ready, expected pickup time, and resume handle",
+    "honest-rubric-fail means a human updates the rubric or changes lead source",
+    "source replenishment beyond same-source-automatic is a scoped create-campaign handoff, never refill-owned provider search",
+    "no campaign creation, provider-family switch, threshold lowering, scheduler writes, sends, archives, deletes, or brief/filter/message/sequence/sender mutation without a separate approval packet"
+  ],
+  "requiredBootstrap": [
+    {
+      "tool": "get_auth_status",
+      "purpose": "Confirm MCP auth before reading workspace or starting a refill run."
+    },
+    {
+      "tool": "get_active_workspace",
+      "purpose": "Resolve explicit workspace evidence when the request did not provide workspaceId."
+    },
+    {
+      "tool": "refill_sends_v2",
+      "requiredValues": {
+        "workspaceId": "{workspaceId}"
+      },
+      "requiredOutput": [
+        "terminal, in_progress, blocked, or dry_run status",
+        "resume handle {runId, fence, gate} when in_progress"
+      ]
+    },
+    {
+      "tool": "get_subskill_prompt",
+      "requiredValues": {
+        "subskillName": "refill-sends-v2-workflow"
+      },
+      "mustReadUntil": {
+        "hasMore": false
+      }
+    },
+    {
+      "tool": "get_subskill_asset",
+      "requiredValues": {
+        "subskillName": "refill-sends-v2-workflow",
+        "assetPath": "core/flow.v1.json"
+      },
+      "mustReadUntil": {
+        "hasMore": false
+      },
+      "validation": {
+        "workflow": "refill-sends-v2-workflow",
+        "versionPrefix": "v1",
+        "requiredTopLevelKeys": [
+          "states",
+          "gateOrder",
+          "enumeratedRungs",
+          "rungLabels",
+          "verification",
+          "laneSources",
+          "terminalReasons",
+          "blockers",
+          "hardRules"
+        ]
+      }
+    },
+    {
+      "tool": "get_refill_plan_v2",
+      "requiredValues": {
+        "workspaceId": "{workspaceId}",
+        "intent": "auto"
+      },
+      "requiredOutput": [
+        "planRevision or workspace_access blocker",
+        "stateRevision",
+        "packet with supplyCensus/censusReason when available",
+        "pipelineDiagnosis checklist when blocked",
+        "sideEffects"
+      ]
+    }
+  ],
+  "gateOrder": ["bootstrap", "plan", "execute", "verify", "report"],
+  "states": [
+    {
+      "id": "bootstrap",
+      "description": "Load the command contract, workflow prompt, flow asset, and workspace facts. A real run starts or resumes a fenced run record; dryRun:true stays read-only and journal-only.",
+      "allowedTools": [
+        "get_auth_status",
+        "get_active_workspace",
+        "list_workspaces",
+        "get_workspace",
+        "refill_sends_v2",
+        "get_subskill_prompt",
+        "get_subskill_asset",
+        "get_refill_plan_v2"
+      ],
+      "onEnter": [
+        {
+          "tool": "get_auth_status"
+        },
+        {
+          "tool": "refill_sends_v2",
+          "requiredFields": ["workspaceId"]
+        },
+        {
+          "tool": "get_subskill_prompt",
+          "requiredValues": {
+            "subskillName": "refill-sends-v2-workflow"
+          }
+        },
+        {
+          "tool": "get_subskill_asset",
+          "requiredValues": {
+            "subskillName": "refill-sends-v2-workflow",
+            "assetPath": "core/flow.v1.json"
+          }
+        }
+      ],
+      "transitions": {
+        "contract_loaded": "plan",
+        "resume_handle_loaded": "verify",
+        "dry_run_requested": "report"
+      }
+    },
+    {
+      "id": "plan",
+      "description": "Read a fresh get_refill_plan_v2 packet with runState fed back from the run record. The loop captures planRevision, stateRevision, and targetShapeRevision, then validates packet coherence before dispatch. The packet's supplyCensus, censusReason, and pipelineDiagnosis checklist explain the rung choice. If packet_incoherent appears, replan once; a second incoherent packet blocks.",
+      "allowedTools": ["get_refill_plan_v2"],
+      "onEnter": [
+        {
+          "tool": "get_refill_plan_v2",
+          "requiredFields": ["workspaceId"],
+          "optionalFields": [
+            "intent",
+            "senderIds",
+            "runState",
+            "journal",
+            "journalNote"
+          ]
+        }
+      ],
+      "requiredOutput": [
+        "planRevision starts with pr1: unless blocker is workspace_access",
+        "stateRevision and targetShapeRevision captured",
+        "chosen label (evergreenRung token) is in enumeratedRungs",
+        "supplyCensus and censusReason justify prep/source/repair choices",
+        "pipelineDiagnosis checklist names firstFailing when blocked",
+        "terminal doneReason maps to terminalReasons"
+      ],
+      "allowedRungsSource": "enumeratedRungs",
+      "doNotAllow": [
+        "add_column",
+        "add_on_demand_leads",
+        "add_rubric_item",
+        "add_teammate",
+        "add_to_comment_campaign",
+        "add_to_connection_campaign",
+        "add_to_inmail_campaign",
+        "archive_campaign",
+        "attach_recommended_sequence",
+        "attach_sequence",
+        "bulk_enrich_with_prospeo",
+        "cancel_campaign_message_preparation",
+        "cancel_lead_import",
+        "capture_post_idea",
+        "check_rubric",
+        "commit_blueprint",
+        "confirm_harvest_job_companies",
+        "confirm_lead_list",
+        "confirm_prospeo_company_accounts",
+        "copy_sender_config",
+        "create_campaign",
+        "create_on_demand_campaign",
+        "create_on_demand_table",
+        "create_workspace",
+        "create_workflow_table",
+        "delete_column",
+        "delete_rubric_item",
+        "duplicate_campaign",
+        "enrich_with_prospeo",
+        "fill_campaign_horizon",
+        "get_or_create_direct_campaign_table",
+        "import_leads",
+        "load_csv_dnc_entries",
+        "load_csv_domains",
+        "load_csv_linkedin_leads",
+        "mark_post_published",
+        "migrate_flat_configs",
+        "pause_campaign",
+        "pause_direct_campaign",
+        "pause_on_demand_campaign",
+        "prepare_campaign_ab_test",
+        "queue_campaign_cells",
+        "queue_cells",
+        "record_campaign_review_batch",
+        "record_engage_proven_search",
+        "refill_sends",
+        "refresh_paid_inmail_credits",
+        "revise_message_template_and_rerun",
+        "save_domain_filters",
+        "save_hook_research",
+        "save_post_draft",
+        "save_rubrics",
+        "send_inbox_draft",
+        "send_inbox_manual_reply",
+        "set_active_workspace",
+        "set_campaign_waterfall_order",
+        "set_company_info",
+        "set_engage_state",
+        "set_engage_style_guide",
+        "set_headline_icp_criteria",
+        "set_sender_routing",
+        "setup_evergreen_campaigns",
+        "start_campaign",
+        "start_campaign_message_preparation",
+        "start_direct_campaign",
+        "start_on_demand_campaign",
+        "update_campaign",
+        "update_campaign_brief",
+        "update_cell",
+        "update_column",
+        "update_inbox_draft",
+        "update_post_draft",
+        "update_published_post_metrics",
+        "update_rubric_item",
+        "upsert_engage_tracked_person",
+        "upsert_rubric"
+      ],
+      "transitions": {
+        "work_named": "execute",
+        "terminal_doneReason": "report",
+        "workspace_access": "report",
+        "packet_incoherent_replan": "plan",
+        "packet_incoherent_blocked": "report"
+      }
+    },
+    {
+      "id": "execute",
+      "description": "Execute exactly the packet head action through refill_sends_v2 internals. Bounded approvals, message preparation, same-source copies, rerun_errored_cells, saved signal continuations, paid-credit refreshes, and pinned-lane starts are allowed only when named by the packet. Execute only the fingerprint captured at the last plan gate; stale packets refuse and return to plan.",
+      "allowedTools": [
+        "refill_sends_v2",
+        "start_campaign_message_preparation",
+        "confirm_lead_list",
+        "import_leads",
+        "search_signals",
+        "select_promising_posts",
+        "start_campaign",
+        "queue_campaign_cells"
+      ],
+      "doNotAllow": [
+        "create_campaign",
+        "create_on_demand_campaign",
+        "setup_evergreen_campaigns",
+        "set_campaign_waterfall_order",
+        "refresh_paid_inmail_credits",
+        "send_inbox_draft",
+        "send_inbox_manual_reply",
+        "update_campaign_brief",
+        "set_headline_icp_criteria",
+        "set_sender_routing"
+      ],
+      "transitions": {
+        "planned_recorded": "verify",
+        "stale_packet": "plan",
+        "non_yolo_continuation": "report",
+        "lease_lost": "report"
+      }
+    },
+    {
+      "id": "verify",
+      "description": "Verify whole-row outcomes before another plan read. Reattach to an own active prep job by requestSource/requestHash; never re-dispatch prep while a matching job is active. Foreign prep waits until clear or blocks foreign_prep_active. wait_for_active_work and wait_for_source_import reread the plan on bounded cadence. wait_for_scheduler is cross-invocation: each tool call polls briefly under the host guard, heartbeats the lease, and returns in_progress sweep guidance so the agent re-invokes refill_sends_v2 with {runId,fence}. The approximately five minute scheduler budget is cumulative at the run level.",
+      "allowedTools": ["refill_sends_v2", "get_refill_plan_v2"],
+      "onEnter": [
+        {
+          "tool": "refill_sends_v2",
+          "requiredFields": ["workspaceId", "runId", "fence"]
+        }
+      ],
+      "hardRules": [
+        "do not re-dispatch prep when an own active job exists; reattach and poll status",
+        "capped_by_scheduler is complete",
+        "replan-driven repair: the planner names rerun_errored_cells, approve_messages, start_campaign, or source work; the loop bounds and refuses",
+        "conversion verdict is journaled from packet facts after the first prep batch; the plan gate withholds a second unproven prep batch",
+        "zero pickup after a confirmed sweep is debugged from pipelineDiagnosis, not waited out forever",
+        "Sales Nav and Prospeo continuation packets render a scoped $sellable:create-campaign [campaignId] handoff for same saved-search identity, import mode add into the same source list, source work only"
+      ],
+      "transitions": {
+        "verify_poll": "verify",
+        "verified": "plan",
+        "in_progress_resume": "verify",
+        "terminal": "report",
+        "blocked": "report"
+      },
+      "repeatUntil": "terminal_or_in_progress_resume_or_blocked"
+    },
+    {
+      "id": "report",
+      "description": "Present the terminal or blocked report. Terminal proof is the run record at g4_terminal with a doneReason plus journal planned->did->outcome lines and a terminal block. loaded_awaiting_scheduler keeps the token for run-record compatibility, but report copy must include remaining-ready count, exact expected pickup time, and the resume handle; never render bare loaded, awaiting scheduler copy. Blocked Sales Nav and Prospeo packets reprint the scoped $sellable:create-campaign [campaignId] handoff text.",
+      "allowedTools": [],
+      "onEnter": [
+        {
+          "action": "present_run_terminal_or_resume_report"
+        }
+      ],
+      "terminal": true
+    }
+  ],
+  "verification": {
+    "requiredProof": [
+      "run record reached g4_terminal with a named doneReason",
+      "journal contains planned -> did -> outcome lines",
+      "journal contains terminal block and index line",
+      "planRevision has pr1: prefix unless blocker is workspace_access",
+      "chosen evergreenRung belongs to enumeratedRungs and has a plain-language rungLabels entry",
+      "managed_waterfall, dashboard_evergreen, or active_campaign lane source recorded",
+      "laneChain recorded when active_campaign chain is selected",
+      "supplyCensus/censusReason and pipelineDiagnosis checklist reviewed when present",
+      "in_progress results include runId, fence, gate, and sweep or wait guidance"
+    ],
+    "notCompletionProof": [
+      "called get_refill_plan_v2 alone",
+      "plan packet alone",
+      "action queue exists but no planned/did/outcome journal evidence",
+      "in_progress continuation without {runId,fence,gate}",
+      "journal absence",
+      "bare loaded awaiting scheduler report without expected pickup time"
+    ]
+  }
+}