@sellable/mcp 0.1.0

package/skills/create-campaign-v2/references/parallel-critique-protocol.md

@@ -0,0 +1,368 @@
+# Parallel Critique Protocol
+
+This reference governs the optional Step 15 critique pass introduced in
+Plan 85-03. Load this file whenever `messaging.critique.enabled === true`
+in `core/auto-execute.yaml`. When the flag is `false`, the plain Step 15
+path runs unchanged and none of the protocol below applies.
+
+## Principle
+
+Step 15 (`auto-execute-messaging`) already generates messages under the
+Phase 84 token contract. The critique pass is a bounded, opt-in quality
+lens on top of that output. It is NOT a second drafting pass. It never
+invents new tokens, new proof, or new personalization, and it never
+ships a rewrite that violates the token contract.
+
+The critique pass is:
+
+- **Bounded.** It runs on `messaging.critique.sampleSize` rows, not
+  the full cohort. Cost is predictable whether the cohort is 50 or 500.
+- **Parallel.** Three fixed critic groups (targeting, copy, voice)
+  run in parallel and return structured JSON.
+- **Synthesized.** One synthesis step merges the three voices into a
+  single rewrite and re-runs the Phase 84 finalizer pass.
+- **Budget-capped.** A trip on `budgetUsdCap` HALTS critique for the
+  remaining sample and continues the plain tail. Cost never explodes
+  silently.
+- **Token-contract preserving.** Any rewrite that introduces an
+  unsupported token, an unresolved token, or invented proof is
+  rejected, and the plain generated message is persisted instead.
+
+## When the Protocol Loads
+
+Load this file at the start of Step 15 if and only if
+`messaging.critique.enabled === true`. Do not load it during Step 13,
+Step 14, or Step 16. Do not load it when the flag is `false` — the
+plain Step 15 path runs unchanged.
+
+If the flag is `true` but any critique knob is unparseable (missing
+`sampleSize`, missing `critics`, missing `synthesis`), skip the pass
+and continue on the plain Step 15 path. Log the config error for
+calibration.
+
+## Inputs
+
+- The messages just drafted by the plain Generate Message cascade
+  call at the top of Step 15.
+- `lead-sample.json`, `lead-filter.md`, `brief.md` (read-only — these
+  are the same artifacts the plain drafter used).
+- `messaging.critique.*` config values from `auto-execute.yaml`.
+- The Phase 84 token contract rules in
+  `references/thomas-revision-filters.md`.
+
+## Step Shape
+
+```text
+if messaging.critique.enabled == false:
+    continue on the plain Step 15 path (no critique, no Opus)
+    return
+
+loaded = load_auto_execute_config()    # already parsed at Step 13
+critique_cfg = loaded.messaging.critique
+
+sample = first critique_cfg.sampleSize rows of the drafted messages
+budget_used = 0.0
+results = []
+
+for row in sample:
+    if budget_used >= critique_cfg.budgetUsdCap:
+        log("budget_cap_tripped", row_id=row.id, budget_used=budget_used)
+        results.append(plain_message(row))       # fall back silently
+        continue
+
+    critics_out = run_parallel_critics(
+        row=row,
+        critics=critique_cfg.critics,
+        per_critic_timeout_s=critique_cfg.perCriticTimeoutSeconds,
+        total_timeout_s=critique_cfg.totalTimeoutSeconds,
+    )
+    # Timed-out critics are recorded as "no opinion" and skipped; the
+    # synthesis proceeds with the remaining voices. A total timeout
+    # falls back to the plain message for this row only.
+
+    rewrite = synthesize(
+        plain=row.plain_message,
+        critics=critics_out,
+        enforce_finalizer_pass=critique_cfg.synthesis.enforceFinalizerPass,
+    )
+
+    if rewrite.violates_token_contract:
+        log("rewrite_rejected_token_contract", row_id=row.id, reason=rewrite.reason)
+        results.append(plain_message(row))       # persist plain, not rewrite
+        continue
+
+    if critique_cfg.opus.enabled and is_highest_value(row, critics_out):
+        if opus_budget_left(critique_cfg.opus):
+            opus_rewrite = craft_message(row, rewrite, critics_out)
+            if not opus_rewrite.violates_token_contract:
+                rewrite = opus_rewrite
+        else:
+            log("opus_budget_cap_tripped", row_id=row.id)
+
+    results.append(rewrite)
+    budget_used += cost_of(critics_out, rewrite)
+
+return results
+```
+
+`is_highest_value(...)` and Opus eligibility live in
+`references/thomas-variant-selection.md`. The synthesis step's
+finalizer pass is the same Phase 84 finalizer pass the plain
+`generate-messages` skill already runs.
+
+## Critic Groups
+
+The three critic groups are fixed. Do NOT invent free-form critics.
+Each critic runs independently, receives the same inputs, and returns
+a strict JSON envelope.
+
+### Targeting critic
+
+- **Focus:** `signal-lead-fit-and-buyer-intent`
+- **Question it answers:** Is the signal or personalization in this
+  message actually supported by the lead row and the validated filter?
+  Does the opener reference something the buyer will recognize as
+  theirs?
+- **Never answers:** sentence-level copy questions, voice questions,
+  motion alignment.
+
+### Copy critic
+
+- **Focus:** `sentence-shape-proof-cta`
+- **Question it answers:** Does the message follow the one-sentence-
+  per-line body shape? Is proof placed where the matched motion
+  expects it? Is the CTA proportional to the signal and useful, not a
+  naked meeting ask?
+- **Never answers:** whether the lead is a good target, whether the
+  tone matches the motion.
+
+### Voice critic
+
+- **Focus:** `tone-motion-alignment`
+- **Question it answers:** Does this read like the Primary Example
+  motion (casual-lowercase if Superpower, dense-credentialed if
+  Superposition)? Does any sentence introduce jargon a 5th-grade
+  reader wouldn't parse? Does the PS carry the right shape (thin
+  narrative, at most two beats)?
+- **Never answers:** targeting, proof math, CTA heaviness.
+
+## Critic JSON Envelope
+
+Every critic returns exactly this envelope. Unknown fields are
+rejected. Missing fields cause the critic to be dropped from synthesis
+(treated as "no opinion") rather than blocking the tail.
+
+```json
+{
+  "criticId": "targeting" | "copy" | "voice",
+  "verdict": "keep" | "revise" | "reject",
+  "revisions": [
+    {
+      "line": "<original sentence or block>",
+      "suggestion": "<rewritten sentence or block>",
+      "reason": "<one-line rationale grounded in brief / lead-sample>"
+    }
+  ],
+  "tokenNotes": [
+    {
+      "token": "{{example}}",
+      "status": "supported" | "unresolved" | "unsupported" | "proposed",
+      "evidence": "<field path in lead-sample.json or brief.md>"
+    }
+  ],
+  "confidence": 0.0
+}
+```
+
+Rules on the envelope:
+
+- `verdict = reject` is reserved for rewrites the critic believes
+  cannot be saved (fake proof request, unsupported token the
+  synthesizer cannot drop, motion mismatch that needs brief revision).
+  A `reject` verdict short-circuits synthesis and falls back to the
+  plain message.
+- `tokenNotes[*].status = "proposed"` is how a critic surfaces a NEW
+  token idea (e.g. a fresh field the brief doesn't yet document). The
+  synthesis step MUST NOT promote a proposed token into the persisted
+  rewrite. Proposed tokens appear in the optional operator review
+  surface only.
+- `revisions[*].suggestion` must contain at most the same set of
+  tokens the plain message used, minus tokens the critic explicitly
+  asked to drop. It may never introduce a token that isn't supported
+  in `tokenNotes`.
+
+## Synthesis
+
+One synthesis step takes the plain message plus the three critic
+envelopes and returns a single rewrite. It runs on the
+`synthesis.model` tier configured in `auto-execute.yaml` (kept
+intentionally vague here so the tier can be retuned without touching
+the protocol file).
+
+Rules:
+
+1. **Token contract first.** The synthesizer enforces the Phase 84
+   token contract verbatim:
+
+   - Use only tokens documented in `brief.md` as supported fields.
+   - Reject any unresolved `{{token}}`.
+   - Reject any token flagged `unsupported` by any critic.
+   - Reject any rewrite that invents a metric, logo, customer,
+     funding detail, or product claim.
+   - A `proposed` token requires human approval and does NOT appear
+     in the persisted rewrite.
+
+2. **One primary example.** Preserve the matched archived motion's
+   voice. Do not blend two motions into one rewrite.
+
+3. **Finalizer pass last.** If `synthesis.enforceFinalizerPass` is
+   `true` (default), re-run the Phase 84 finalizer pass on the
+   synthesis output. The finalizer is the last guardrail against
+   critic-introduced token drift. A finalizer failure falls back to
+   the plain message for that row.
+
+4. **PS earns its place.** If the synthesizer adds or moves a PS, the
+   PS must pass the revision-filter shape rules (thin narrative, at
+   most two beats, no resume list, no fake credential).
+
+5. **Conservative merge.** When two critics disagree, prefer the
+   critic whose concern maps to the motion's weakest current link
+   (e.g. prefer the copy critic when the plain message is too dense;
+   prefer the voice critic when the plain message is tone-off).
+   Never synthesize toward a third option the critics didn't raise.
+
+## Budget Control
+
+Two independent caps:
+
+- **`budgetUsdCap`** — total for critics + synthesis across the whole
+  pass. Tripping it halts critique for the remaining sample rows and
+  persists the plain message for those rows. The trip is logged as
+  `budget_cap_tripped` with the row id and the running cost. The
+  autonomous tail continues; Step 15 does NOT stall.
+- **`opus.budgetUsdCap`** — separate cap for the Opus subset. Opus
+  trip halts Opus escalation for the remaining rows of the current
+  pass only; non-Opus critique continues normally. Also logged as
+  `opus_budget_cap_tripped`.
+
+Neither cap causes an escalation (in the `escalation-ladder.md`
+sense). Budget trips are planned early exits of the critique path,
+not skill-level failures.
+
+## Timeout Handling
+
+- **`perCriticTimeoutSeconds`** (default 30) — a critic that misses
+  this cap is treated as "no opinion" for this row. Synthesis
+  proceeds with the remaining critic voices. Logged as
+  `critic_timeout` with `criticId` and `rowId`.
+- **`totalTimeoutSeconds`** (default 120) — if the full parallel
+  group has not returned by this cap, the tail falls back to the
+  plain generated message for this row. Logged as
+  `critique_total_timeout` with `rowId`.
+
+Timeouts never block the tail. A timed-out row is persisted as the
+plain message and the loop continues to the next row.
+
+## Fake Proof Rejection
+
+`rejectOnFakeProof: true` (default) means: any rewrite that
+introduces a metric, logo, customer name, funding detail, or product
+claim that is not supported by `brief.md` is rejected. The rejection
+logs `rewrite_rejected_fake_proof` with the offending claim and the
+row id. The plain generated message is persisted for that row.
+
+Critics may ask for stronger proof; the synthesizer may only
+surface stronger proof that is already in the brief. If the brief
+cannot support the critic's ask, the rewrite falls back.
+
+## Unsupported Token Rejection
+
+`rejectOnUnsupportedToken: true` (default) means: any rewrite that
+introduces a `{{token}}` not declared in the brief is rejected. Two
+sub-rules:
+
+1. **Unresolved tokens** (tokens that expand to empty) are rejected.
+   The plain message's unresolved-token safety rules still apply.
+2. **Proposed tokens** (new fields a critic believes should exist)
+   may surface for operator review but do NOT appear in the
+   persisted rewrite. The synthesizer strips them before finalization.
+
+A rewrite that only differs from the plain message by an unsupported
+token is a silent fallback to the plain message.
+
+## Opus / Craft-Message Subset
+
+Opus is reserved for the highest-value subset only. Default config
+leaves `opus.enabled = false`. When enabled, the rules from
+`references/thomas-variant-selection.md` decide which rows earn Opus.
+Hard caps:
+
+- `opus.maxMessagesPerPass` (default 2) — never escalate more rows
+  than this per critique pass.
+- `opus.budgetUsdCap` (default 1.5 USD) — independent of the overall
+  critique budget.
+
+An Opus rewrite runs the same token-contract enforcement as the
+non-Opus synthesis output. A fake-proof or unsupported-token Opus
+rewrite is rejected the same way.
+
+## Fallback Behavior
+
+Every critique-side failure mode falls back to the plain generated
+message for that row. None of them escalate:
+
+- Critique flag `false` → no critic calls, no Opus, plain Step 15
+  path runs.
+- Config unparseable → no critic calls, plain Step 15 path runs.
+- Per-critic timeout → synthesis proceeds without that critic.
+- Total timeout → plain message persisted for that row.
+- Budget cap tripped → plain message persisted for remaining rows.
+- Opus budget tripped → rest of pass runs non-Opus.
+- Token contract violation (fake proof, unsupported token, proposed
+  token leaked) → plain message persisted for that row.
+- Synthesis finalizer pass failure → plain message persisted.
+
+The tail continues. Step 15 does NOT stall on critique failures.
+
+## Logging
+
+When `logging.logEveryThresholdTrip === true` (default), log each of
+these events with the row id (when applicable) and the relevant
+figures:
+
+- `critique_pass_start` (row count, sample cap)
+- `critic_result` (criticId, verdict, confidence)
+- `critic_timeout` (criticId, rowId)
+- `critique_total_timeout` (rowId)
+- `rewrite_rejected_token_contract` (rowId, reason)
+- `rewrite_rejected_fake_proof` (rowId, claim)
+- `budget_cap_tripped` (rowId, budgetUsed)
+- `opus_selected` (rowId, reason)
+- `opus_budget_cap_tripped` (rowId)
+- `critique_pass_end` (rowsCritiqued, rowsFallback, totalCost)
+
+These logs drive `auto-execute.yaml` tuning after 3-5 real critique
+passes.
+
+## Hard Rules
+
+- Critique is OFF by default. Plan 85-02 never flips the flag.
+- Sample size is bounded by `messaging.critique.sampleSize`. The
+  pass NEVER runs against the full cohort.
+- Three critic groups only: targeting, copy, voice. Do NOT add a
+  fourth.
+- Every critic returns the structured JSON envelope above. Free-form
+  critic output is discarded.
+- The synthesizer enforces the Phase 84 token contract verbatim.
+- The synthesis step MUST re-run the finalizer pass when
+  `enforceFinalizerPass === true` (default).
+- Opus is reserved for the highest-value subset only and gated
+  independently from the main critique flag.
+- Budget trips halt the pass gracefully and continue the tail on
+  plain messages.
+- Fake proof and unsupported tokens ALWAYS fall back to the plain
+  message — never ship the rewrite.
+- A proposed new token may surface for human approval but does NOT
+  appear in the persisted rewrite.
+- No critique failure escalates in the `escalation-ladder.md` sense.
+  The plain path is always a valid fallback.

package/skills/create-campaign-v2/references/sample-validation-loop.md

@@ -0,0 +1,289 @@
+# Sample Validation Loop
+
+This reference governs Step 14 (`validate-sample`) of the Plan 85-02
+autonomous tail. Load this file before enriching + scoring the sample, and
+on every revision round.
+
+## Principle
+
+We spend a bounded review batch (default 25 rows) to prove fit before the
+user spends credits on hundreds more leads. The sample loop has one job:
+answer the question "do we have enough real passing examples for the user to
+judge this campaign?"
+
+If the answer is yes, proceed to Step 15 messaging for the review batch. If
+the answer is no, diagnose whether the brief is wrong or the list is wrong,
+and either revise brief autonomously OR escalate to the user — never
+auto-revise leads.
+
+## Inputs
+
+- `CampaignOffer.currentStep === "validate-sample"` (set at end of Step 13)
+- Imported review batch from Step 13 (size: `importLimit`, default 25)
+- Config from `auto-execute.yaml`: `sample.sampleSize`,
+  `sample.minProjectedPass`, `sample.maxRevisionRounds`
+- Persisted counter `revisionRound` (starts at 0 on first entry; persists
+  across resume)
+
+## Loop Shape
+
+```text
+1. pick first sampleSize rows from the imported review batch
+
+2. paginate the campaign table to collect enrichCellIds where
+   enrichStatus = "pending" for the sample rows
+   - use get_rows_minimal (NOT get_rows); the default response embeds
+     full LinkedIn post content in carryData (~2KB/row)
+   - strip carryData from every row BEFORE retaining in tail context
+     (see §Known Tool Behaviors #4)
+
+3. queue_cells(enrichCellIds, batchSize <= 100)
+   - confirm_lead_list does NOT auto-enqueue enrichment on imports
+     into an existing workflow table; Step 14 must enqueue manually
+     (see §Known Tool Behaviors #1)
+
+4. wait for enrichment completion (poll via get_rows_minimal with
+   the enrichment batch ids; NOT by calling wait_for_rubric_results
+   before rubric was scheduled)
+
+5. check_rubric(sample)
+
+6. wait_for_rubric_results(sample, targetCount = <cohortSize>)
+   - cohortSize = stats.totalRows of the enrichment batch, or the
+     imported batch count
+   - default targetCount=25 matches the default review batch, but pass the
+     explicit batch count anyway so future larger expansion batches do not
+     accidentally stop early
+     (see §Known Tool Behaviors #3)
+
+7. read the result via a subagent; extract ONLY:
+   - ready: boolean
+   - passRate.completed: number
+   - stats: object
+   Never retain the full rows payload in tail context.
+   - 25 rows ≈ 67KB of payload (full post bodies in carryData)
+   - 100 rows ≈ 268KB; 500 rows ≈ 1.3MB — blows context on Opus
+     (see §Known Tool Behaviors #2)
+
+8. compute metrics:
+   passInSample       = count of review-batch rows where rubric passed
+   projectedPass      = round(passInSample / sampleSize * importLimit)
+
+9. branch:
+   if projectedPass >= minProjectedPass:
+       proceed to Step 15 (auto-execute-messaging) with this review batch
+   else:
+       diagnose (see Brief-vs-List Diagnosis below)
+       revisionRound += 1
+       if revisionRound > maxRevisionRounds:
+           ESCALATE (see references/escalation-ladder.md)
+       else if diagnosis == "brief":
+           autonomous update_campaign_brief with diagnostic
+           rerun sample from step 1 of this loop
+       else if diagnosis == "list":
+           ESCALATE — do NOT auto-revise leads
+       else:  # unknown
+           ESCALATE — do not guess
+```
+
+## Known Tool Behaviors (work around these)
+
+These are observed tool behaviors that Step 14 must compensate for.
+They are documented here so the tail does not accidentally assume
+"enrichment auto-runs" or "rubric wait is context-cheap."
+
+### 1. `confirm_lead_list` does NOT auto-enqueue enrichment
+
+Observed: on imports into an existing workflow table (e.g. signal
+discovery), `confirm_lead_list` returns `autoEnrichedCount=0`,
+`enrichmentCellsCopied=0`, `enrichmentCellsPending=0`. Enrichment does
+NOT kick off on its own.
+
+Workaround: Step 14 must explicitly paginate the campaign table,
+collect pending `enrichCellId`s, and call `queue_cells` before any
+`wait_for_rubric_results` call. The plan text cannot assume
+enrichment runs silently after import.
+
+### 2. `wait_for_rubric_results` returns full rows payload
+
+Observed: default response includes `carryData.Post Content` with
+whole LinkedIn post bodies. ~67KB per 25 rows. ~268KB per 100 rows.
+Retaining the full payload across tail turns blows Opus context.
+
+Workaround (short-term): invoke `wait_for_rubric_results` inside a
+subagent turn and extract ONLY `ready`, `passRate.completed`, and
+`stats`. Never put the raw rows payload back into the tail's own
+context. Prefer `get_rows_minimal` (not `get_rows`) when row-level
+inspection is required, and strip `carryData` before retention.
+
+Workaround (long-term): add a `includeRows=false` / stats-only mode
+to `wait_for_rubric_results` at the MCP tool level. Tracked as a
+backlog item; until then the subagent-read pattern is the contract.
+
+### 3. `wait_for_rubric_results.targetCount` defaults to 25
+
+Observed: default `targetCount=25` returns `ready=true` after the first 25
+rubric completions. This matches the default review batch, but if a future
+expansion batch is larger, pass the explicit batch size instead of relying on
+the default. The completion semantic is `passRate.completed`, NOT "table
+fully enriched and scored."
+
+Workaround: always pass `targetCount = cohortSize` explicitly. Compute
+`cohortSize` from `stats.totalRows` or the imported batch count.
+Treat `needsEnrichCount > 0` after `ready=true` as "workers still
+processing the queued batch," not "new cells need queuing" —
+DO NOT re-call `queue_cells` in that case.
+
+### 4. `get_rows_minimal.carryData` includes full post content
+
+Observed: cell-discovery pagination during the enrich-queue step
+returns rows whose `carryData` includes full LinkedIn post content
+(~2KB/row). Iterating the full cohort with default options and
+keeping the result in the tail turn blows context the same way (2).
+
+Workaround: strip `carryData` from each row IMMEDIATELY after reading
+and BEFORE retaining. Prefer a minimal projection (name, title,
+company, enrichCellId, enrichStatus) over the default shape.
+
+## Projected Pass Math
+
+```text
+projectedPass = round(passInSample / sampleSize * importLimit)
+```
+
+Worked examples with defaults (sampleSize=25, importLimit=25):
+
+| passInSample | projectedPass | Handoff? (minProjectedPass=5) |
+| ------------ | ------------- | ----------------------------- |
+| 0            | 0             | No — escalate or revise       |
+| 4            | 4             | No — escalate or revise       |
+| 5            | 5             | Yes — exactly at floor        |
+| 10           | 10            | Yes                           |
+| 15           | 15            | Yes                           |
+| 25           | 25            | Yes                           |
+
+When non-default importLimit/sampleSize are configured, the math scales
+the same way. In the default review-batch mode, the sample size equals the
+import limit, so the projection is the actual review-batch pass count.
+
+## Brief-vs-List Diagnosis
+
+Before blindly revising, classify the failure. Three buckets:
+
+### Brief problem
+
+Rubric fires cleanly but the passing sample fails voice/value-prop
+alignment, OR messages repeatedly fail token contract, OR pass criteria
+reflect a thesis the brief doesn't actually support.
+
+Signal examples:
+
+- Sample has ICP-matching leads, but drafted messages (if we drafted any)
+  fail token resolution because the brief's proof inventory is thin.
+- Rubric pass rate is OK in absolute terms but the passing rows all fail
+  a downstream anchor (e.g. "mentions X pain point") that the brief
+  never supplied evidence for.
+- Same token repeatedly can't resolve across multiple sample runs.
+
+Action: autonomous `update_campaign_brief` with the specific diagnostic
+(e.g. "add case-study proof for pain point Y"). Rerun sample. Increment
+revisionRound.
+
+#### Worked example — horizontal-SaaS seniority drift (Plan 95-03 Ambral)
+
+Symptom observed during Plan 95-03 Ambral walkthrough: 14/30 (47%)
+sample was FIT+MAYBE, but the MAYBE cluster was driven by sub-D-round
+"VP Customer Success" titles. These rows match the title whitelist but
+likely don't own budget at that stage.
+
+Classification: **BRIEF problem**, not list.
+
+Reasoning:
+
+- Rubric fires cleanly (reasons match brief §5 ICP).
+- Sample is NOT wrong-function or wrong-geo — titles are correct.
+- The gap is in the brief's §5 seniority rule, which is too permissive
+  for horizontal-SaaS (where "VP CS" at a Series B can be a 2-person
+  team with no budget authority, vs "VP CS" at Series D which is a
+  proper budget owner).
+
+Action: autonomous `update_campaign_brief` with diagnostic "tighten
+§5 seniority to D-round and later; Series B-C VP CS titles do not
+own expansion budget in horizontal-SaaS verticals." Rerun sample.
+Expected: 2-3 rows graduate from MAYBE → FIT after the seniority
+tightening + the corresponding rubric tightening. revisionRound = 1.
+
+Do NOT classify this as a list problem. The list is sourced correctly;
+the brief's buyer-specificity is under-tuned.
+
+### List problem
+
+Rubric fires cleanly, but the sample is overwhelmingly outside ICP, OR
+enrichment yields blanks (name/title/company missing), OR rubric pass
+rate is zero with no pattern that brief editing could fix.
+
+Signal examples:
+
+- 10/10 rows are wrong function / wrong seniority / wrong geo.
+- 8/10 rows enrich to empty strings for the tokens the brief needs.
+- Rubric passes 0 rows and the failure reasons are all "not ICP."
+- **Marketplace supply-side contamination:** >20% of sample rows match
+  the brief §14 forbidden side (e.g. Skillsync sample contains
+  supply-side GitHub contributors; the brief explicitly forbids
+  outbound to that side). This is a sourcing contamination, NOT a
+  brief tightening. Escalate for operator re-source. See
+  `references/filter-leads.md` §Marketplace safety rail.
+
+Action: STOP. Escalate with the explicit diagnostic "the sourced list
+looks bad — revise leads or start over." Do NOT call
+`update_campaign_brief`. Do NOT silently rerun `import_leads`.
+
+### Unknown
+
+Neither bucket is clean. Signals are mixed, or the rubric result is
+uninterpretable (e.g. `save_rubrics` was bypassed upstream and the
+rubric never actually fired).
+
+Action: STOP. Escalate. Do not guess.
+
+## Token Contract Check
+
+When `messaging.tokenContract === "strict"` (default), the sample
+validation loop ALSO dry-checks token resolution on the enriched sample
+before declaring success. If tokens fail to resolve on the sample, that's
+a brief problem (the brief is asking for tokens the enrichment can't
+provide), not a list problem — unless enrichment is returning blanks,
+which is a list problem.
+
+Prefer the brief diagnosis when a specific token is missing and the brief
+could be edited to stop asking for it. Prefer the list diagnosis when
+enrichment itself is incomplete.
+
+## Revision Round Counter
+
+- Increments only on a failed round (projectedPass < minProjectedPass +
+  diagnosis acted on).
+- Persists with the committed campaign metadata; does NOT live in
+  session memory.
+- On skill resume, reads the persisted counter. Does NOT reset to 0.
+- Trip: `revisionRound > maxRevisionRounds` ⇒ escalate.
+- Logged on every increment so `auto-execute.yaml` tuning has data.
+
+## Logging
+
+When `logging.logEveryThresholdTrip === true` (default), log:
+
+- Every `projectedPass` computation (with inputs + result).
+- Every diagnosis decision (brief / list / unknown) and the reason.
+- Every `revisionRound` increment.
+- Every escalation trigger (which condition fired).
+
+## Hard Rules
+
+- A list problem NEVER triggers an autonomous `update_campaign_brief`.
+- `projectedPass` math uses rounding, not floor/ceil.
+- The counter persists across resume.
+- The loop never retries the same sample silently — a rerun always goes
+  through diagnosis + brief revision first.
+- The loop never calls `import_leads` again. Full-cohort import is a
+  Step 13 action, not a recovery action for a bad sample.