@sellable/mcp 0.1.793 → 0.1.794

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

@@ -4,6 +4,10 @@ description: Closed execution contract for the canonical fenced refill-sends coo
 visibility: internal
 allowed-tools:
   - mcp__sellable__refill_sends
+  - mcp__sellable__refill_v3_advance
+  - mcp__sellable__refill_v3_continue
+  - mcp__sellable__list_workspaces
+  - mcp__sellable__get_active_workspace
   - mcp__sellable__get_subskill_asset
   - mcp__sellable__get_refill_target_plan
   - mcp__sellable__get_scheduler_fill_capacity
@@ -12,11 +16,51 @@ allowed-tools:
 
 # Refill Sends Workflow
 
-This is the closed executor companion to the public `refill-sends` skill.
-The public Mermaid diagrams define product order; `core/flow.v1.json` defines
-the deterministic gates. `refill_sends` is the only execution owner. Do not
-manually reproduce the ladder with lower-level campaign, source, preparation,
-approval, or scheduler tools.
+This is the closed executor companion to the public `refill-sends` skill. It
+carries BOTH routes, and it decides between them itself.
+
+## Route selection — do this FIRST
+
+Decide the route before loading any flow asset and before the next coordinator
+call. Do NOT treat an earlier tool call as the decision: if a refill was already
+opened on the wrong route, this section overrides it. The predicate is the same
+MECHANICAL one the public skill uses, 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. Load `core/flow.v3.json` and follow
+  [Refill V3](#refill-v3-one-deterministic-step-per-call). Do not load
+  `core/flow.v1.json`, do not call `get_refill_target_plan`, and do not call
+  `refill_sends` — including when an earlier call in this session already did.
+- **No → take the V1 route.** The installed server predates Refill V3, so
+  `refill_sends` is the only coordinator available. Load `core/flow.v1.json` and
+  follow the V1 sections below.
+
+Never infer the route from a workspace flag, a campaign field, a tool result, or
+the operator's wording: no such cutover signal exists. Report the selected route
+explicitly before the first coordinator call.
+
+## Which asset to load
+
+The asset follows the route selected above:
+
+- **V3 → `core/flow.v3.json`.**
+- **V1 → `core/flow.v1.json`.**
+
+The public Mermaid diagrams define product order; the loaded flow asset defines
+the deterministic gates. Exactly one coordinator owns execution per route:
+`refill_v3_advance` on V3, `refill_sends` on V1. Do not manually reproduce
+either ladder with lower-level campaign, source, preparation, approval, or
+scheduler tools.
+
+## V1 route
+
+Everything from here to [Refill V3](#refill-v3-one-deterministic-step-per-call)
+applies only when `core/flow.v1.json` was the loaded asset. On this route
+`refill_sends` is the only execution owner. Do not manually reproduce the ladder
+with lower-level campaign, source, preparation, approval, or scheduler tools.
 
 Every mode renders the same read-only D1 plan before any mutation. Default
 non-yolo mode asks for explicit acceptance of that packet and later transitions.
@@ -311,3 +355,66 @@ readiness authority, reporting context, and a returned `laneScope` receipt.
   capacity, sweep/status, and bounded receipts. Never use individual cell ids,
   Prisma, SQL, direct database access, or production-environment scripts as
   completion proof. Redact raw prospect and copy data.
+
+## Refill V3: one deterministic step per call
+
+This is the DEFAULT route whenever `refill_v3_advance` is exposed.
+`core/flow.v3.json` is the V3 execution contract and `refill_v3_advance` is its
+ONLY execution owner. Load the entire asset and verify a COMPATIBLE version
+before the first call: same major (`v3`) and minor at or above the minimum
+`v3.0`, so `v3.0` and `v3.7` both load while `v2.x` and `v4.x` are refused with a
+typed verdict. Report that version explicitly.
+
+Resolve the workspace BEFORE the first call. `workspaceId` must be an EXACT id on
+every automation call, exactly as the V1 route already requires: when the operator
+names a workspace, call `list_workspaces` first and match that name to its id, and
+fall back to the configured or active workspace ONLY when the operator named none.
+If nothing accessible matches the named workspace, or more than one does, stop and
+say so rather than using the configured workspace, and never change the shared
+active workspace to steer an automation.
+
+Decide the AUTONOMY GRANT before the first call, from the operator's words alone,
+and keep it fixed for the whole run. `--yolo` (or an explicit "just do it, don't
+check back") means `yolo: true` on EVERY advance call; anything else means omit
+the key. The grant is not a mode and selects no campaign — WHICH campaign may
+start is derived from the workspace's own campaigns — it decides only whether
+this run may start one at all, and whether you may keep going unattended:
+
+| | `yolo: true` | key omitted |
+| --- | --- | --- |
+| paused derived-evergreen start | one may be started once a row's active campaigns are exhausted, arriving as an ordinary executed `start_evergreen_campaign` action | none: the backend REFUSES the start and answers the exhaustion terminal instead |
+| loop | call `refill_v3_advance` again immediately, through to a terminal, without checking back | surface the result and ASK before the next call |
+
+Never infer the grant from a workspace flag, a campaign field, a tool result, an
+idle-looking workspace, or a previous terminal; never set it to make a run finish,
+clear a wait, or retry a refusal; and never change it part-way through a run.
+
+Call `refill_v3_advance` with `{workspaceId, scope}` plus `yolo` when granted.
+There is no mode, continuation, task receipt, retry counter, cursor, row, action,
+or receipt-fact input; the backend parser refuses any of them before it observes
+anything. Losing a prior result is harmless, because every invocation reconstructs
+from fresh world state plus server-loaded authority receipts.
+
+Each call answers with exactly one of five results:
+
+- `advanced` — the action ALREADY RAN and was already followed by its mandatory
+  exact-scope reread. Surface the action identity, the receipt, and the
+  replacement observation, then call `refill_v3_advance` again (asking first when
+  the grant was withheld). Never execute `action.kind` and never call its
+  authority again.
+- `campaign_attention_required` — the ONE model judgment in this flow. The
+  backend already chose exactly one campaign and bounded its evidence. Load
+  `refill-sends-work-campaign`, pass the packet through, and let
+  `refill_v3_continue` revalidate the packet against a fresh advance result,
+  execute at most one existing authority, and re-observe the exact sender/date.
+  Then call `refill_v3_advance` again.
+- `awaiting_external_change` — stop and report the scoped wait verbatim.
+- `complete` — stop and report the terminal code verbatim.
+- `blocked` — stop and report the typed business blocker verbatim.
+
+This workflow chooses nothing. It never reads capacity, supply, family, or reason
+fields to decide what to do next; never declares a terminal, an exhaustion
+verdict, or a health classification; never holds a counter or a cursor between
+calls; and never calls a placement, scheduler, source, enrichment, approval, or
+send tool directly. `refill_sends` and `core/flow.v1.json` remain the unchanged
+V1 surface.

package/skills/refill-sends-workflow/core/flow.v3.json

@@ -0,0 +1,209 @@
+{
+  "version": "v3.0",
+  "workflow": "refill-sends-workflow",
+  "asset": "core/flow.v3.json",
+  "principle": "refill_v3_advance is the only execution owner. It chooses ONE exact next action from one fresh observation, executes at most that one authority, and rereads the exact affected scope before answering. This asset is a THIN CALLER: it calls advance, surfaces the already-executed result, and routes exactly one result variant to the campaign subskill. It contains no row, campaign, lane, action, health, source, retry, or terminal choice of its own.",
+  "versionGate": {
+    "minimumVersion": "v3.0",
+    "compatibleMajor": "v3",
+    "versionPolicy": "compatible_range",
+    "note": "The authoritative consumer is the INSTALLED skill cache, so the gate is a compatible RANGE. Same major and minor at or above the minimum is accepted, so v3.0 and v3.7 both load while v2.x and v4.x are refused with a typed verdict."
+  },
+  "requiredBootstrap": [
+    {
+      "tool": "get_subskill_prompt",
+      "requiredValues": {
+        "subskillName": "refill-sends-workflow"
+      },
+      "mustReadUntil": {
+        "hasMore": false
+      }
+    },
+    {
+      "tool": "get_subskill_asset",
+      "requiredValues": {
+        "subskillName": "refill-sends-workflow",
+        "assetPath": "core/flow.v3.json"
+      },
+      "mustReadUntil": {
+        "hasMore": false
+      },
+      "validation": {
+        "workflow": "refill-sends-workflow",
+        "versionPolicy": "compatible_range",
+        "minimumVersion": "v3.0",
+        "compatibleMajor": "v3",
+        "requiredTopLevelKeys": [
+          "versionGate",
+          "loop",
+          "resultHandling",
+          "forbidden"
+        ]
+      }
+    }
+  ],
+  "deterministicOwner": {
+    "selector": "computeNextRefillV3Action",
+    "coordinator": "advanceRefillV3",
+    "note": "Both live on the backend. The caller cannot see, influence, or reproduce the selection."
+  },
+  "tools": {
+    "advance": "refill_v3_advance",
+    "campaignAttentionSubskill": "refill-sends-work-campaign",
+    "campaignAttentionAuthority": "refill_v3_continue"
+  },
+  "workspaceResolution": {
+    "appliesWhen": "always, BEFORE the first advance call",
+    "allowedTools": [
+      "list_workspaces",
+      "get_active_workspace"
+    ],
+    "rules": [
+      "An automation call requires an exact explicit workspaceId. Never pass a workspace NAME to refill_v3_advance and never let it fall back to the configured workspace when the operator named one.",
+      "When the operator names a workspace, call list_workspaces FIRST and match that name to an exact workspaceId; pass that id on every advance call for the rest of the run.",
+      "Use the configured or active workspace ONLY when the operator named no workspace at all.",
+      "Never change the shared active workspace to steer an automation: active-workspace mutation is not automation control."
+    ],
+    "failClosed": {
+      "noMatch": "If no accessible workspace matches the named one, STOP and say so with the name you were given and the accessible names. Do not fall back to the configured workspace.",
+      "ambiguous": "If more than one accessible workspace matches, STOP and ask which one. Do not guess and do not pick the first."
+    },
+    "note": "Ported verbatim in intent from flow.v1.json's scope_resolution state, which V3 dropped in the cutover: the V1 route already required 'an exact explicit workspaceId' and forbade active-workspace mutation as automation control."
+  },
+  "autonomy": {
+    "appliesWhen": "always, BEFORE the first advance call, and unchanged for the rest of the run",
+    "question": "Did the OPERATOR ask for --yolo (or an equivalent explicit 'just do it, don't check back')? Read it from their words only.",
+    "input": {
+      "key": "yolo",
+      "type": "boolean",
+      "pass": "yolo:true on EVERY advance call of a granted run; omit the key entirely otherwise",
+      "note": "yolo is the operator's AUTONOMY GRANT. It is not a mode, it selects no campaign, and it has no third value. WHICH campaign may start stays derived from the workspace's own campaigns; the grant only says whether this run may start one at all."
+    },
+    "grants": {
+      "execution": "One already-eligible PAUSED derived-evergreen campaign may be started once a row's active campaigns are exhausted. It arrives as an ordinary executed start_evergreen_campaign action.",
+      "loop": "Keep calling advance through re-observation until a terminal, without checking back with the operator between calls."
+    },
+    "withheld": {
+      "execution": "No paused campaign is ever started. The backend REFUSES the start and answers the exhaustion terminal instead, so this is enforced, not merely requested.",
+      "loop": "Report the current result and the state it implies, and ASK before calling advance again. Present what the next call would do; do not traverse to a terminal unattended."
+    },
+    "forbidden": [
+      "inferring the grant from a workspace flag, a campaign field, a tool result, an idle-looking workspace, or a previous call's terminal",
+      "setting yolo:true to make a run finish, to clear a wait, or to retry a refusal",
+      "changing the grant part-way through a run",
+      "asking the backend for a particular campaign to start: the grant authorizes a start, it never names one"
+    ],
+    "note": "Restores V1's discipline, which the V3 cutover dropped: flow.v1.json's yoloMode carries approvalSource 'explicit_yolo_flag' and lists start_paused_campaign among autoExecutableActions, and V1's refill_sends states 'In --yolo or after one Accept ... a fresh exact start_paused_campaign packet authorizes starting only that selected PAUSED fallback'. A bare non-yolo V1 run rendered the packet and asked first."
+  },
+  "loop": {
+    "call": {
+      "tool": "refill_v3_advance",
+      "inputKeys": [
+        "workspaceId",
+        "scope",
+        "yolo"
+      ],
+      "note": "Pass workspaceId and scope with the values the host resolved once, plus yolo:true only when the autonomy step granted it. workspaceId is the EXACT id workspaceResolution produced, never a name and never an implicit config default when the operator named a workspace. There is no mode, continuation, task receipt, retry counter, cursor, row, action, or receipt-fact input, and a call that supplies one is refused by the backend parser before any observation.",
+      "requiredInputKeys": [
+        "workspaceId",
+        "scope"
+      ]
+    },
+    "repeatWhile": [
+      "advanced",
+      "campaign_attention_required"
+    ],
+    "stopOn": [
+      "awaiting_external_change",
+      "complete",
+      "blocked"
+    ],
+    "note": "Call advance again with the SAME two keys. Losing a prior result is harmless: every invocation reconstructs from fresh world state plus server-loaded authority receipts.",
+    "repeatPolicy": {
+      "granted": "Call advance again immediately, without checking back.",
+      "withheld": "Surface the result, then ASK before the next call. The repeatWhile set is unchanged \u2014 only who decides to take the next step changes."
+    }
+  },
+  "resultHandling": {
+    "advanced": {
+      "alreadyExecuted": true,
+      "surface": [
+        "action.kind",
+        "action.senderId",
+        "action.date",
+        "action.lane",
+        "action.campaignId",
+        "receipt.status",
+        "replacementObservation"
+      ],
+      "then": "call the advance tool again",
+      "note": "The action ALREADY RAN and was already followed by its mandatory reread. Never execute the action and never call its authority a second time."
+    },
+    "campaign_attention_required": {
+      "alreadyExecuted": false,
+      "route": {
+        "subskill": "refill-sends-work-campaign",
+        "pass": [
+          "packet.scope",
+          "packet.evidence"
+        ],
+        "returnThrough": "refill_v3_continue",
+        "returnInput": [
+          "workspaceId",
+          "scope",
+          "packet",
+          "decision",
+          "yolo"
+        ]
+      },
+      "then": "call the advance tool again",
+      "note": "This is the ONE model judgment in the flow. The backend already selected exactly one campaign and bounded the evidence; the subskill chooses one action from its own closed vocabulary and its deterministic authority validates, executes, and re-observes it."
+    },
+    "awaiting_external_change": {
+      "alreadyExecuted": false,
+      "surface": [
+        "deferral.senderId",
+        "deferral.date",
+        "deferral.lane",
+        "deferral.code",
+        "deferral.resumeAt"
+      ],
+      "then": "stop and report the scoped wait verbatim"
+    },
+    "complete": {
+      "alreadyExecuted": false,
+      "surface": [
+        "terminal",
+        "observation"
+      ],
+      "then": "stop and report the terminal code verbatim"
+    },
+    "blocked": {
+      "alreadyExecuted": false,
+      "surface": [
+        "blocker.senderId",
+        "blocker.date",
+        "blocker.lane",
+        "blocker.code",
+        "blocker.permanent"
+      ],
+      "then": "stop and report the typed business blocker verbatim"
+    }
+  },
+  "forbidden": [
+    "choosing a sender, date, lane, campaign, or action from this JSON or from prompt prose",
+    "re-executing an already-executed result or calling its mutation authority a second time",
+    "reading capacity, supply, family, or reason fields to decide what to do next",
+    "holding an attempt count, a retry counter, a cursor, or any continuation between calls",
+    "declaring a terminal, an exhaustion verdict, or a health classification of its own",
+    "calling a placement, scheduler, source, enrichment, approval, or send tool directly",
+    "translating a typed business blocker into a transport error or a generic refusal"
+  ],
+  "verification": [
+    "The reported flow version satisfied the compatible RANGE and was reported explicitly.",
+    "Every advance call carried exactly workspaceId and scope.",
+    "Every already-executed result was surfaced, never re-executed.",
+    "Only campaign_attention_required loaded the campaign subskill.",
+    "The run stopped on the first awaiting_external_change, complete, or blocked result."
+  ]
+}