@sellable/mcp 0.1.0

package/skills/create-campaign-v2/references/draft-lifecycle.md

@@ -0,0 +1,110 @@
+# Draft Lifecycle
+
+Phase 84 validates the Phase 83 brief through chained artifacts in one draft
+directory:
+
+`.sellable/create-campaign-v2/drafts/{workspace-slug}/{campaign-slug}/`
+
+Required files as the chain advances:
+
+```text
+brief.md
+lead-review.md
+lead-sample.json
+lead-filter.md
+message-validation.md
+rubric.json   # optional
+```
+
+## Artifact Roles
+
+- `brief.md`
+  - stable Phase 83 thesis
+  - preserved during validation
+- `lead-review.md`
+  - human-readable analysis of the preview run
+- `lead-sample.json`
+  - machine-readable lead sample for filter and message validation
+- `lead-filter.md`
+  - primary keep/exclude output for the middle step
+  - owns required keep rules, required exclude rules, sample false positives,
+    pass-rate judgment, and the final recommendation
+- `rubric.json`
+  - optional implementation sidecar only
+  - must be derived from `lead-filter.md`, not designed separately
+- `message-validation.md`
+  - final message check against the validated lead set
+
+## Serial Step Order
+
+Run in this order only:
+
+1. find leads
+2. filter leads
+3. generate message
+
+Do not skip ahead unless the required upstream artifacts already exist and are
+complete.
+
+## Atomic Writes
+
+Every artifact edit must be written as:
+
+1. read the current artifact if it exists
+2. compute the full replacement contents
+3. write `{artifact}.tmp`
+4. rename `{artifact}.tmp` -> `{artifact}`
+
+If the write fails before rename, the old artifact remains the valid state.
+
+## Resume Rules
+
+- `brief.md` only -> run `find leads`
+- `lead-review.md` + `lead-sample.json` present -> run `filter leads` and
+  `generate message` from the same find-leads basis
+- `lead-filter.md` present and `message-validation.md` missing -> run
+  `generate message`
+- `message-validation.md` present and `lead-filter.md` missing -> run
+  `filter leads`
+- `message-validation.md` + `lead-filter.md` present -> reconcile and stop,
+  validation complete
+
+Invalid partial states must stop for repair:
+
+- `lead-review.md` exists but `lead-sample.json` is missing
+- `lead-sample.json` exists but `lead-review.md` is missing
+- `lead-filter.md` exists without both upstream lead artifacts
+- approval packet or commit gate exists without both `message-validation.md`
+  and `lead-filter.md`
+
+## Revision Rules
+
+- `revise-brief`
+  - preserve `brief.md`
+  - delete `lead-review.md`
+  - delete `lead-sample.json`
+  - delete `lead-filter.md`
+  - delete `message-validation.md`
+  - delete `rubric.json` if present
+- `revise-leads`
+  - delete `lead-review.md`
+  - delete `lead-sample.json`
+  - delete downstream artifacts (`lead-filter.md`, `message-validation.md`, `rubric.json`)
+- `revise-filter`
+  - preserve lead preview artifacts
+  - delete `lead-filter.md`
+  - delete `message-validation.md`
+  - delete `rubric.json` if present
+- `revise-message`
+  - preserve upstream artifacts
+  - delete `message-validation.md`
+
+## No-Mutation Boundary
+
+During Phase 84, the artifact chain is local draft state only. Do not:
+
+- create or update a `CampaignOffer`
+- import leads
+- persist a selected lead list
+- create workflow rows
+- attach sequences

package/skills/create-campaign-v2/references/escalation-ladder.md

@@ -0,0 +1,119 @@
+# Escalation Ladder
+
+This reference governs when the Plan 85-02 autonomous tail STOPS and returns
+control to the user. Load this file whenever the tail needs to decide
+between continuing autonomously, retrying, or escalating.
+
+## Principle
+
+The autonomous tail is optimistic but not reckless. It retries bounded
+transient failures, diagnoses whether a bad signal is a brief problem or a
+list problem, and escalates cleanly when autonomous correction would either
+loop indefinitely or silently ship bad state.
+
+Escalation is a first-class exit — not a failure. A clean escalation leaves
+the campaign resumable, preserves `CampaignOffer.currentStep` at the failing
+step, and surfaces an actionable options menu.
+
+## Escalation Conditions
+
+Stop the autonomous tail and escalate to the user when any of the following
+fire. The list is intentionally ordered from loudest to quietest — when
+multiple could fire, pick the loudest.
+
+1. **Zero leads imported** (Step 13 `import_leads` returned 0 usable rows).
+   Hard fail. There is nothing to validate, nothing to message.
+2. **Sender missing or disabled** at any tail step that needs it
+   (sequence attach, messaging, greenlight). Hard fail — no send path.
+3. **Sequence validation fails** (attach step rejects the sequence). Hard
+   fail with the sequence error surfaced verbatim.
+4. **`save_rubrics` was already bypassed** and the rubric step produces
+   unusable results. The rubric never fired — the tail cannot make a
+   brief-vs-list decision without it.
+5. **List problem diagnosed** in Step 14 (sample is overwhelmingly outside
+   ICP, or enrichment yields blanks). Do NOT auto-revise the brief; the
+   list itself needs operator attention. See
+   `references/sample-validation-loop.md` for the brief-vs-list decision
+   tree.
+6. **`revisionRound > maxRevisionRounds`** (default cap is 3). The loop
+   tried and failed `maxRevisionRounds` times; one more try is not going
+   to change the outcome. On stale resume the counter does NOT reset —
+   see Resume Counter Rule below.
+7. **Same tool + same error repeats** beyond `retry.sameToolSameError`
+   (default 2). The fourth retry of the same enrichment 5xx is thrash.
+8. **User greenlight on a failed or paused campaign**. If the user says
+   "start" but the campaign is in an error/paused state that the skill
+   cannot atomically recover from, refuse the start and surface why.
+
+## Diagnosis Before Escalation
+
+When the tail hits a sample-validation trip (projectedPass <
+minProjectedPass), it MUST diagnose before escalating or revising:
+
+- **Brief problem** → autonomous `update_campaign_brief` with the
+  specific diagnostic, rerun sample. Loop counter increments.
+- **List problem** → STOP. Escalate with an explicit "the sourced list
+  looks bad — revise leads or start over" message. Never auto-revise
+  leads.
+- **Unknown** → STOP. Escalate rather than guess which revision path
+  would help.
+
+The diagnosis itself is logged (which path was chosen and why) so
+`auto-execute.yaml` tuning has real evidence later.
+
+## Resume Counter Rule
+
+`revisionRound` persists across skill resume. If a session closes with the
+counter at 2 and the user reopens and resumes, the counter is still at 2 —
+ONE more revision round is allowed before the 3-round cap trips. Stale
+resume must still respect the cap. Do NOT reset to 0 on resume.
+
+The counter lives with the campaign draft/committed metadata, not in
+volatile session state.
+
+## Retry vs Escalate
+
+Bounded retries are fine. Infinite retries are not. Rules of thumb:
+
+- **Retry** a single transient error on the same tool up to
+  `retry.sameToolSameError` (default 2). Includes 5xx, socket timeout,
+  rate-limit 429 with backoff.
+- **Escalate** when the error is the same tool + same error code
+  beyond the cap, or when the tool is returning 4xx auth/permission
+  errors that won't change on retry.
+- **Diagnose, then revise or escalate** when the tool succeeded but the
+  result is low-quality (rubric pass rate collapses, tokens cannot
+  resolve on the sample). Do not retry the same sample — the sample
+  itself is the signal, not the tool.
+
+## Escalation Output
+
+When escalating, the skill:
+
+1. Writes the last diagnostic + revision history to the workflow-table
+   `Notes` column or a skill-level artifact so the operator can see what
+   was tried.
+2. Leaves `CampaignOffer.currentStep` at the failing step (so resuming
+   the skill picks up exactly where it stopped — no silent rollback, no
+   silent advance).
+3. Re-surfaces the watch link using `references/watch-link-handoff.md`.
+4. Presents an actionable options menu via `AskUserQuestion`:
+   - `revise-brief` — go back to Phase 83/84 brief editing
+   - `revise-leads` — go back to Phase 84 find-leads
+   - `abort` — stop and clean up (moves committed dir under `.aborted/`
+     if the user wants to cold-start)
+   - `resume-from-<step>` — retry from the failing step (e.g.
+     `resume-from-validate-sample`), useful when the operator corrected
+     something externally (e.g. re-enabled a sender)
+
+## Hard Rules
+
+- A list problem NEVER triggers an autonomous `update_campaign_brief`.
+  Brief revision is for brief-shaped failures only.
+- The revision-round counter NEVER resets on resume.
+- Escalation NEVER silently rolls back campaign state. The campaign row
+  exists; only `currentStep` tells us where to resume.
+- The watch link IS re-surfaced on escalation so the user can inspect
+  state directly.
+- Escalation is not an error in the sense that the skill crashed — it's
+  a planned exit. Surface it calmly.