@sellable/mcp 0.1.0

package/skills/create-campaign-v2/core/auto-execute.README.md

@@ -0,0 +1,219 @@
+# Autonomous Tail Configuration
+
+This file narrates `auto-execute.yaml`. The YAML is the source of truth; this
+README explains intent, tuning guidance, and how each knob affects the
+Plan 85-02 autonomous tail.
+
+## When this file is loaded
+
+The skill reads `auto-execute.yaml` exactly once, at the start of the
+autonomous tail (Step 13, `auto-execute-leads`). All subsequent steps (14
+validate-sample, 15 auto-execute-messaging, 16 awaiting-user-greenlight)
+read the already-parsed config; they do not re-load the YAML mid-run.
+
+Config values are NOT written to DB. They live on the skill side and
+influence tool arguments (e.g. `importLimit` flows into `import_leads`
+`targetLeadCount` arg, `sampleSize` flows into the first N rows pulled from
+the imported review batch for validation).
+
+## Sections
+
+### `import`
+
+- **`importLimit`** — Review-batch size imported in Step 13. The tail MUST
+  NOT exceed this cap before the user reviews the first batch and explicitly
+  approves expansion. If the user wants 250 leads, run a later expansion step;
+  do not spend credits on all 250 during the default approval tail.
+- **`provider`** — Inherited from the Phase 84 commit decision (saved in
+  the committed brief / campaign metadata). Present here so the tail can
+  narrate which provider it's running against; it does NOT override the
+  committed provider.
+
+### `sample`
+
+- **`sampleSize`** — How many rows the validation loop pulls from the
+  imported review batch. In v2 this matches the review-batch cap
+  (default 25), so the user sees enough real rows to judge the campaign
+  without spending credits on hundreds more.
+- **`minProjectedPass`** — Passing-message floor required before handoff.
+  The default requires 5 passing examples from the 25-row review batch.
+  Math:
+  ```text
+  projectedPass = round(passInSample / sampleSize * importLimit)
+  ```
+  With defaults (sampleSize=25, importLimit=25), `projectedPass` equals
+  the actual review-batch pass count. 5 passing rows is exactly at the
+  floor.
+- **`maxRevisionRounds`** — Hard cap before escalating to the user. A
+  revision round is one full sample pass that triggered brief revision
+  and retried. On stale resume the counter does NOT reset.
+
+### `messaging`
+
+- **`tokenContract`** — `strict` rejects unresolved/unsupported tokens
+  before handing the review batch to the user. `relaxed` logs warnings but
+  proceeds.
+  Default `strict` because live campaign state shouldn't ship messages
+  with unresolved templating.
+- **`critique.enabled`** — Plan 85-03 feature flag for the message
+  critique pass. Plan 85-02 reads the flag but never flips it; it
+  stays false by default. Only flip to `true` after dry-running the
+  critique protocol against a real sample and confirming the token
+  contract still holds on the rewritten output. See
+  `references/parallel-critique-protocol.md` for the full protocol.
+- **`critique.sampleSize`** — Hard cap on the number of messages sent
+  through parallel critics. Bounded on purpose so cost stays
+  predictable whether the cohort is 50 or 500. Defaults to 5.
+- **`critique.budgetUsdCap`** — Total dollar cap across critics +
+  synthesis for a single critique pass. Tripping the cap HALTS
+  critique for the remaining sample and continues the plain tail
+  (Step 15 plain path). The trip is logged.
+- **`critique.perCriticTimeoutSeconds`** — Per-critic timeout. A
+  critic that blows past it is treated as "no opinion" and synthesis
+  proceeds with the remaining voices. Never blocks the tail.
+- **`critique.totalTimeoutSeconds`** — Total critique-pass timeout.
+  Blown cap → tail falls back to the plain generated message for that
+  row. Never blocks the tail.
+- **`critique.critics`** — Three fixed critic groups (targeting, copy,
+  voice). Each critic returns structured JSON the synthesis step can
+  merge. Do NOT add free-form critics; stay on the three groups.
+- **`critique.synthesis.enforceFinalizerPass`** — When `true`, the
+  synthesizer re-runs the Phase 84 finalizer pass on its rewrite.
+  This is the last guardrail against critic-introduced token drift.
+  Default stays `true`.
+- **`critique.opus.enabled`** — Flag gating Opus / craft-message
+  usage. Opus is reserved for the highest-value subset only. Stays
+  off by default; flip on only when the targeting critic flags a
+  high-priority row and budget allows.
+- **`critique.opus.maxMessagesPerPass`** — Hard cap on the number of
+  rows that can be escalated to Opus per critique pass. Defaults to 2.
+- **`critique.opus.budgetUsdCap`** — Dollar ceiling for the Opus
+  subset, independent of the overall critique budget. Opus trip halts
+  Opus for this pass only; non-Opus critique continues.
+- **`critique.rejectOnFakeProof`** — When `true`, any critic rewrite
+  that introduces invented proof (metric, logo, customer, funding
+  detail) is rejected and the plain message is persisted. Default
+  `true`.
+- **`critique.rejectOnUnsupportedToken`** — When `true`, any rewrite
+  that introduces a token not declared in the brief is rejected. A
+  proposed new token may be surfaced for operator review but does
+  NOT appear in the persisted rewrite. Default `true`.
+
+### `handoff`
+
+- **`autoStart`** — HARD-CODED `false` in v2. The autonomous tail never
+  calls `start_campaign` on its own. The value is exposed here for
+  clarity so future calibration doesn't accidentally enable it.
+- **`orientation`** — One-line user-facing string surfaced in Step 16
+  with the watch link. Keep it short and actionable. The dual greenlight
+  channel (UI button or Claude reply) is documented in
+  `references/final-handoff-contract.md`.
+
+### `retry`
+
+- **`sameToolSameError`** — Cap on same-tool-same-error retries before
+  escalating. Prevents thrash when (e.g.) enrichment 5xx's repeatedly on
+  the same sample.
+
+### `logging`
+
+- **`logEveryThresholdTrip`** — When true, every threshold trip
+  (projectedPass floor, retry cap, revision cap, hard-fail) gets a log
+  line. Keep this on until we've tuned the YAML over 3-5 real runs.
+
+## Tuning After Live Runs
+
+After 3-5 real campaigns complete the tail, review the threshold-trip
+logs and adjust:
+
+- `importLimit` higher only if users consistently ask for larger review
+  batches and credit spend is acceptable.
+- `sampleSize` higher if a 25-row review batch is not enough to judge
+  quality for a specific market.
+- `minProjectedPass` lower only if fewer than 5 passing examples is still
+  enough for a confident user decision.
+- `maxRevisionRounds` should rarely change; 3 is already generous. If
+  brief revision is hitting the cap often, the brief template upstream
+  is the real problem, not this knob.
+- `sameToolSameError` higher only if a flaky provider is otherwise
+  healthy. Prefer fixing the provider.
+
+## What This File Does NOT Control
+
+- Tool-level auth / workspace scoping — lives in MCP auth config.
+- The commit gate choices — locked by
+  `references/approval-gate-framing.md` and `core/flow.v2.json`.
+- Watch link surfacing — locked by `references/watch-link-handoff.md`.
+- The final-handoff contract (UI vs Claude greenlight) — locked by
+  `references/final-handoff-contract.md`.
+
+## Related References
+
+- `references/sample-validation-loop.md` — the brief-vs-list diagnosis
+  decision tree for Step 14.
+- `references/escalation-ladder.md` — the ordered stop-and-escalate
+  conditions that short-circuit the tail.
+- `references/final-handoff-contract.md` — the dual greenlight channel
+  that takes Step 16 into a running campaign.
+- `references/parallel-critique-protocol.md` — Plan 85-03 Step 15
+  critique protocol: bounded sample, parallel critics, synthesis,
+  budget caps, and token-contract enforcement.
+- `references/thomas-variant-selection.md` — Plan 85-03 rules for
+  which rows earn an Opus / craft-message rewrite.
+- `references/thomas-revision-filters.md` — the positive-target and
+  automatic-revision filters that gate any critique rewrite.
+
+## Flipping `messaging.critique.enabled` to true (dry-run protocol)
+
+The critique flag stays `false` by default because an enabled critique
+pass invents new tokens + costs ~$2 per sample pass — both of which
+can silently degrade a live campaign if the protocol isn't solid. Plan
+85-02 ships the protocol; flipping the default requires dry-run
+evidence.
+
+### Required evidence before flipping default
+
+1. **Quality lift on ≥ 1 non-trivial archetype.** Run critique-on vs
+   critique-off on the same fixture (e.g. Ambral enterprise horizontal
+   SaaS, where voice drift is expected to be more pronounced than
+   IncidentFox founder-peer mode). Compare winner messages via the
+   Filter 8 catalog check + a human read. Critique must produce
+   measurably better output on ≥ 60% of the bounded sample.
+
+2. **Budget cap holds.** Total critique pass cost must stay under
+   `messaging.critique.budgetUsdCap` (default $2.00) across 3
+   consecutive dry-run passes. One overshoot trips the budget cap
+   correctly but signals the archetype is critique-expensive;
+   re-evaluate per archetype.
+
+3. **Token contract finalizer passes on every synthesis output.** The
+   finalizer pass (Phase 84 token contract) is the last guardrail
+   against critic-introduced token drift. If any synthesis output
+   fails the finalizer in dry-run, the protocol is not safe to flip.
+
+4. **No regression on founder-peer archetypes.** IncidentFox +
+   Skillsync style voices must NOT degrade under critique. If critique
+   over-corrects a casually-written Block 1 into a structured
+   value-prop, critique is wrong for those archetypes — decide
+   per-archetype, not globally.
+
+### Dry-run process
+
+1. Keep `messaging.critique.enabled: false` at the YAML default.
+2. On a single VPS UAT run, set `SELLABLE_CREATE_CAMPAIGN_V2_UAT_CRITIQUE=on`
+   (runner override) to exercise critique without touching the default.
+3. Compare results with `SELLABLE_CREATE_CAMPAIGN_V2_UAT_CRITIQUE=off`
+   on the same fixture.
+4. Record delta in the UAT artifact run folder.
+5. After 3 clean dry-runs across ≥ 2 archetypes, flip the YAML default.
+
+The fixture runner matrix mode (`critique=matrix`) already runs both
+flavors per fixture — use it for the dry-run comparison.
+
+### Why the flag exists as a flag
+
+Critique is a **net quality lift** in theory. In practice it depends
+on the archetype's voice — critique helps structured enterprise voice,
+can hurt casually-founder voice, and flips unpredictably with budget.
+Shipping critique default-off with an explicit enable path prevents
+silent regression on live campaigns.

package/skills/create-campaign-v2/core/auto-execute.yaml

@@ -0,0 +1,121 @@
+# Autonomous tail configuration for create-campaign-v2 (Plan 85-02)
+#
+# This file controls the post-commit review-batch tail that runs AFTER the
+# commit gate succeeds and the campaign has been atomically minted. The tail
+# does NOT call `start_campaign` on its own and does NOT spend enrichment
+# credits on the full cohort before the user has reviewed a real sample.
+#
+# Tune after 3-5 real campaign runs. Log every threshold trip so tuning is
+# evidence-based, not guess-based. See `auto-execute.README.md` for a
+# narrative walkthrough and `references/sample-validation-loop.md` for the
+# decision tree.
+
+version: 1
+
+import:
+  # Initial review batch imported in Step 13 before the sample validation
+  # loop. Import + enrichment must never exceed this cap before the user
+  # reviews the sample and explicitly asks to expand.
+  importLimit: 25
+  # Provider is inherited from the Phase 84 commit decision (not re-selected
+  # here). The autonomous tail reads the committed value rather than
+  # overriding it.
+  provider: prospeo
+
+sample:
+  # Rows pulled from the imported cohort for the validation loop. In v2 this
+  # equals the review-batch cap so the user sees a meaningful first batch
+  # without spending credits on hundreds of rows.
+  sampleSize: 25
+  # Projected first-batch passing count required to proceed to sample
+  # messaging. This is not approval to scale the full source list.
+  # projectedPass = round(passInSample / sampleSize * importLimit).
+  minProjectedPass: 5
+  # Hard cap on revision loops before escalating to the user. On a stale
+  # resume the counter does NOT reset — the 3-round cap holds across
+  # sessions.
+  maxRevisionRounds: 3
+
+messaging:
+  # strict = reject any unresolved or unsupported tokens before scaling.
+  # relaxed = warn but allow. Default is strict for live campaign state.
+  tokenContract: strict
+  critique:
+    # Feature flag for the message critique pass shipped in Plan 85-03.
+    # Stays false by default. Flip to true only after the critique
+    # protocol has been dry-run against a real sample.
+    enabled: false
+    # Hard cap on the subset of messages sent through parallel critics.
+    # Critique runs on a bounded sample (NOT the full cohort), so the
+    # cost stays predictable whether the cohort is 50 or 500.
+    sampleSize: 5
+    # Total dollar cap for a single critique pass (sum across critics +
+    # synthesis). Trip halts critique for the remaining sample and
+    # continues the plain tail. Tripping is logged for tuning.
+    budgetUsdCap: 2.0
+    # Per-critic timeout. A critic that blows past this is treated as
+    # "no opinion" and the synthesis proceeds with the remaining voices.
+    # Does NOT block the tail.
+    perCriticTimeoutSeconds: 30
+    # Total critique-pass timeout. If the full parallel group has not
+    # returned by this cap, the tail falls back to the plain generated
+    # message. Does NOT block the tail.
+    totalTimeoutSeconds: 120
+    # Three fixed critic groups. Each group returns structured JSON.
+    # Synthesis merges opinions back into ONE rewritten message that
+    # obeys the token contract verbatim.
+    critics:
+      - id: targeting
+        label: Targeting critic
+        focus: signal-lead-fit-and-buyer-intent
+      - id: copy
+        label: Copy critic
+        focus: sentence-shape-proof-cta
+      - id: voice
+        label: Voice critic
+        focus: tone-motion-alignment
+    synthesis:
+      # Model tier used to merge critic JSON into the final rewrite.
+      # The rewrite MUST pass the token contract finalizer pass before
+      # being persisted — synthesis never ships a message that invents
+      # tokens, proof, or personalization.
+      model: synthesizer
+      # When true, the synthesis step is required to re-run the Phase
+      # 84 finalizer pass on its output. The finalizer is the last
+      # guardrail against critic-introduced token drift.
+      enforceFinalizerPass: true
+    opus:
+      # Opus / craft-message is reserved for the highest-value subset
+      # only. Count is a hard cap per critique pass. Selection lives
+      # in references/thomas-variant-selection.md.
+      enabled: false
+      maxMessagesPerPass: 2
+      # Dollar ceiling for the Opus subset, separate from the overall
+      # critique budget. Opus trip halts Opus for this pass only; the
+      # non-Opus critique continues.
+      budgetUsdCap: 1.5
+    rejectOnFakeProof: true
+    rejectOnUnsupportedToken: true
+
+handoff:
+  # HARD-CODED false in v2. The autonomous tail never calls
+  # `start_campaign` on its own. Present here for clarity so future tuning
+  # doesn't accidentally flip it.
+  autoStart: false
+  # Orientation surfaced in Step 16 ("awaiting-user-greenlight") along with
+  # the watch link. Keep this short and user-facing.
+  orientation: >-
+    Review the first 25 enriched leads and messages. If they look good,
+    approve/start this review batch or ask Claude to expand the next batch
+    before spending credits on more leads.
+
+retry:
+  # Stop after N repeats of the same tool hitting the same error. Prevents
+  # tight thrash loops (e.g. enrichment repeatedly 5xx'ing on the same
+  # sample).
+  sameToolSameError: 2
+
+logging:
+  # When true, every threshold trip (projectedPass floor, retry cap,
+  # revision cap, hard-fail) is logged for later calibration.
+  logEveryThresholdTrip: true