Clipping engine, standard operating procedure

Built from SPEC.md v3.1 (2026-09-20). If this file and SPEC.md disagree, SPEC.md wins.

This is two SOPs in one file.

Part A is the machine's SOP: what the engine does on its own, every run.

Part B is your SOP: what to do on each exception, and only on an exception.

Part C is the daily and weekly rhythm.

Part D is the phase gates, as a checklist.

Part E is one table: what "done" means for every stage.

Anything marked Phase 0, in progress is not on disk yet. Another agent is building

those pieces right now under engine/core/. Everything else named here exists today,

at the path given.

---

PART A: THE MACHINE'S SOP

Preamble: cadence, health check, kill switch, test mode

Cadence. Runs twice a day, 07:15 and 15:15, under the launchd job

com.ralphwest.clipping.daily, which runs engine/daily.py. One full pass through

the 20 stages below. Always finishes. Always sleeps.

Heartbeat watch. A second launchd job, com.ralphwest.clipping.heartbeat,

runs engine/core/watchdog.py every 2 hours. It checks if controls/heartbeat

is older than 14 hours; if so, pages. This detects a stalled loop that silence alone

cannot page on.

Stage 0, Health, runs first, before Discover.

• Starts: every scheduled run.
• Does: 1. Check every adapter with a read-only call. 2. Check free

disk space. 3. Read controls/KILL and controls/TEST_MODE. 4. Write

a health record.

• Done: health record on disk, every dependency marked ok or down.
• Stops: any critical dependency down. Whole loop exits after the report.
• Resumes: next scheduled run, or the dependency comes back.
• If it fails: class transient. Repeats across runs surface as

heartbeat_missing, since Sleep never gets reached either.

• Phase 0, in progress. No Health module exists yet. engine/daily.py has no

pre-flight check today, it starts straight into polling.

Kill switch, controls/KILL. Present, nothing that touches money or a

platform runs. Discover, Score, Report still run. Remove it, everything resumes.

Test mode, controls/TEST_MODE. Present, publish and submit run the full

path and stop one call short of the real platform, writing what they would have

sent to dryrun/. **The engine ships in test mode and stays there until Phase

1's gate in Part D is met.**

Phase 0, in progress. Neither file exists yet, nor does controls/ itself.

In practice the engine is already test-mode-only today, since Stage 12 has no

working TikTok adapter. Nothing can go out regardless of any flag.

---

Stage 1: Discover

• Starts: Health passes.
• Does: 1. Load marketplaces.json by its priority field. 2. Poll

every non-manual marketplace via engine/campaign_poll.py and

engine/marketplaces.py. 3. Parse raw campaigns (Whop, Vyro, LiquidClips).

1. Stamp last_seen. 5. Log the count to logs/daily.log.

• Done: campaigns.json shows updated last_seen for every pollable

marketplace this run.

• Stops: one marketplace fails 3 polls in a row. Flagged, others continue.
• Resumes: manual re-enable, or the next scheduled run.
• If it fails: class transient, retried 1m/5m/30m/2h/12h, reclassifies

unknown after 5 tries.

• Phase 0, in progress: the per-marketplace 3-strikes counter is not wired.

engine/daily.py wraps discover-and-score in one try/except today.

Stage 2: Sync

• Starts: Discover done.
• Does: 1. Compare this poll to the last. 2. Mark ended after 3

missed polls. 3. Update pool and spend deltas. 4. Recompute burn rate

and runway (already built, engine/campaigns.py).

• Done: every campaign's burn_rate_per_day, runway_days, last_seen are current.
• Stops: never.
• Resumes: not applicable, runs every pass.
• If it fails: class transient on a file lock, unknown on a missing field.
• Phase 0, in progress: the "3 missed polls, mark ended" step is not built.

Burn rate and runway already compute in engine/campaigns.py.

Stage 3: Verify

• Starts: a campaign is new, or its rules-doc hash changed.
• Does: 1. Fetch the rules document. 2. Parse approved_sources[].

1. Capture payout terms. 4. Hash the doc, for change detection.
2. Give up after 3 tries, write needs_human: rules_doc.

• Done: approved_sources[] populated, terms captured or marked unknown.
• Stops: rules doc unreachable after 3 tries.
• Resumes: a human pastes the doc URL. See Part B.
• If it fails: class human after 3 tries, transient before.
• Phase 0, in progress. No Verify pass exists yet. Nothing on disk populates

approved_sources[] today.

Stage 4: Score

• Starts: verified campaigns exist.
• Does: 1. Apply hard rejects first: brand safety, off-lane, geo, pool

floor, rating floor. 2. Compute the seven weighted factors. 3. Call

Gemini flash-lite once per campaign, cached forever. 4. Write score,

score_parts{}, eligible, reject[].

• Done: every verified campaign carries all 7 score_parts, a score,

and eligible with a reason when false.

• Stops: never.
• Resumes: not applicable.
• If it fails: class unknown on missing inputs. Escalate, never guess a score.
• Built today in engine/campaigns.py and campaign_tracker.py (repo root).

Stage 5: Allocate

• Starts: campaigns are scored.
• Does: 1. Rank by score, engine/selection.py. 2. Pick 3 to 5, at

most 2 per marketplace, skip reliability: bad. 3. Check each pick

has a warm account in its lane, else queue it behind one. 4. Revert any

dropped pick to watching.

• Done: campaigns.json shows 3 to 5 selected/active campaigns,

each with an account assigned.

• Stops: no eligible campaign has a lane account.
• Resumes: an account is registered in that lane. See Part B.
• If it fails: class human, needs_human: account:.
• Built in engine/selection.py. Lane-to-account assignment is an open item.

Stage 6: Ingest

• Starts: an active campaign has an approved source not yet downloaded.
• Does: 1. Read approved_sources[]. 2. Check the URL is literally

on that list before any call, refuse otherwise. 3. Download via

engine/ingest.py (yt-dlp, captions first, Whisper fallback). 4. Record a checksum.

• Done: file on disk under jobs//, checksum recorded, URL provably

in approved_sources[].

• Stops: download fails 3 times.
• Resumes: source re-approved, or the URL fixed.
• If it fails: class transient (network), class human if never approved.
• Built in engine/ingest.py. URL validation against approved_sources[] is an open item; legacy watch_sources.py path must migrate to this gate before Phase 1.

Stage 7: Analyze

• Starts: a source finishes Ingest.
• Does: 1. Use the cached transcript. 2. Window into candidates via

engine/pick.py, killing sponsor reads and intros. 3. Score each on hook,

payoff, emotion, quotability, one Gemini call. 4. Store timestamped

moments with scores and a prompt version.

• Done: candidate moments with timestamps and scores in the job's metadata.
• Stops: the transcript comes back empty.
• Resumes: a fresh source, or Ingest retried.
• If it fails: class transient on a temporary transcript failure,

unknown if there is no audio at all.

• Built in engine/pick.py. Prompt-version stamping into prompts/ is an open item.

Stage 8: Render

• Starts: an analyzed source has unrendered winners, free disk over 5 GB.
• Does: 1. Cut each moment via engine/produce.py, reframe to

1. 2. Burn captions,

lay the hook card over the first 2.6s. 3. Render N variants via

engine/variants.py. 4. Write the mp4 files under jobs//.

• Done: mp4 exists, probe shows 1080x1920, duration in range, audio present.
• Stops: ffmpeg errors 3 times on one clip.
• Resumes: retried on backoff.
• If it fails: class transient, escalates to unknown after 5 tries.
• Built in engine/produce.py and engine/variants.py. Disk-free gate and campaign duration-range validation are open items.

Stage 9: QA

• Starts: a clip is rendered.
• Does: 1. Check duration in range. 2. Check captions in the safe

zone, never over source text. 3. Check a hook in the first 3s.

1. Check file size under the platform limit. 5. Check no duplicate

hash already on that platform.

• Done: clip marked qa_passed with every check recorded, or qa_failed

naming the failure.

• Stops: any check fails. Goes to qa_failed, never auto-requeued.
• Resumes: a human override, or a rerender. See Part B.
• If it fails: class human. qa_failed is terminal, not a retry.
• Phase 0, in progress. No QA module exists. No clip is validated before

Schedule today. Close this gap before Phase 1.

Stage 10: Schedule

• Starts: qa_passed clips exist, an account has allowance today.
• Does: 1. Load accounts from accounts.json via engine/schedule.py.

1. Fill each account's daily allowance from the asset pool. 3. Respect

warm-up stage, minimum gap, no repeated variant on one platform.

1. Jitter posting time, 8am to 10pm. 5. Write queue.json.

• Done: queue.json shows every asset queued with a slot, or unplaced

with a reason.

• Stops: no account has allowance. Nothing scheduled, not an error.
• Resumes: an account ages into its next warm-up stage.
• If it fails: not applicable, this stage only produces queued or

unplaced rows.

• Built in engine/schedule.py. QA gate integration is pending (QA module does not exist yet).

Stage 11: Pre-publish

• Starts: a scheduled slot is due now.
• Does: 1. Write the idempotency key before any call. 2. Check

controls/KILL is absent. 3. Check the account and campaign are active.

1. Check the daily quota is not exhausted. 5. Read controls/TEST_MODE.

• Done: due_now.json lists every slot that passed all 5 checks.
• Stops: any check is false. Slot deferred with the reason, not an error.
• Resumes: the blocking condition clears.
• If it fails: a gate, not a failure. Reappears once the condition clears.
• Built today, partially: engine/publish.py finds due, queued slots

and writes due_now.json. Phase 0, in progress: none of the 5 checks run

yet, the controls don't exist on disk.

Stage 12: Publish

• Starts: Pre-publish passed.
• Does: 1. Call PublishAdapter.publish(clip, account). 2. Mark

the key complete, record the post id or URL. 3. Open publish_failed

with retry_after if the adapter cannot run.

• Done: a post id or URL recorded against the clip.
• Stops: the adapter cannot run. Today, always, for TikTok, no REST path

exists (tested 2026-09-19).

• Resumes: the adapter comes back, or a human publishes and pastes the URL.
• If it fails: class human. See Part B.
• Today: engine/publish.py never calls a publish adapter. It reports

what is due. A human, or a Claude session with the Higgsfield MCP tools,

posts it.

Stage 13: Confirm

• Starts: a clip is published.
• Does: 1. Fetch the post URL. 2. Check it resolves, video

present, view count reads. 3. Retry hourly for 24h if not confirmed

in 30 min. 4. Escalate after 24h.

• Done: post record shows confirmed: true with a readable view count.
• Stops: 24h pass unconfirmed.
• Resumes: not applicable, it escalates instead.
• If it fails: class transient for 24h, then unknown.
• Phase 0, in progress. No Confirm module exists yet.

Stage 14: Submit

• Starts: a clip is confirmed.
• Does: 1. Submit the URL via MarketplaceAdapter.submit. 2. Store

a submission id or screenshot. 3. Open an exception with the URL and

campaign if the adapter cannot submit.

• Done: URL on file with the campaign, proof stored.
• Stops: the submit adapter is unavailable for that marketplace.
• Resumes: a human submits it and marks it done. See Part B.
• If it fails: class human, "submit not capable."
• Built in engine/core/adapters/whop.py. Submit capability is pending, requires browser automation with persisted login.

Stage 15: Track

• Starts: any post older than 1h.
• Does: 1. Call PublishAdapter.stats(post_id). 2. Record the

views delta to metrics.json. 3. Skip, don't fail, if the adapter is down.

• Done: metrics.json shows updated views and checked for the post.
• Stops: never a hard stop, adapter-down just skips this pass.
• Resumes: next pass.
• If it fails: class transient, retried next run.
• Partially built. engine/metrics.py has update() to record a pull. Automatic stats adapter calls and live tracking are pending items.

Stage 16: Reconcile

• Starts: daily.
• Does: 1. Pull platform-reported earnings per campaign. 2. Compute

views x cpm_net. 3. Pull the actual bank or wallet change. 4. Compare

all three, open an exception on any mismatch over 5%.

• Done: three numbers agree within 5%, or an open exception names the gap.
• Stops: never, it runs every day.
• Resumes: not applicable.
• If it fails: class unknown, reconcile_mismatch. See Part B.
• Phase 0, in progress. No Reconcile module exists. metrics.json's schema

is missing campaign_id, submitted, approved, paid.

Stage 17: Learn

• Starts: weekly, or 20+ new measured posts.
• Does: 1. Recompute historical performance per marketplace. 2. Update

reliability (3 late payouts flips a marketplace to bad). 3. Re-run

Stage 5. 4. Shift experiment allocation toward the winning arm, 20% floor.

• Done: reliability updated, the historical-performance term changed, a

new selection run logged.

• Stops: never, it is scheduled.
• Resumes: not applicable.
• If it fails: class unknown on missing data. Never run on stale numbers.
• Partially built. engine/metrics.py's summary() computes a basic

score-vs-views correlation today. Phase 0, in progress: the full feedback

loop back into Score and Allocate.

Stage 18: Cleanup

• Starts: always, every pass.
• Does: 1. Delete source files over 30 days old, fully spent.

1. Remove temp dirs under jobs/_src/. 3. Rotate logs/daily.log.

• Done: disk stays bounded, nothing past its retention window remains.
• Stops: never.
• Resumes: not applicable.
• If it fails: class transient (locked file), retried next pass.
• Phase 0, in progress. No cleanup pass exists. Files accumulate today.

Stage 19: Report

• Starts: always, last.
• Does: 1. Write briefs/YYYY-MM-DD.md, opening with, in order: money

earned yesterday and to date, open escalations, posts

published/confirmed/submitted, active campaigns and their runway, heartbeat

time. 2. Send the heartbeat line to Telegram. 3. Put the exception

count and money numbers in the first five lines.

• Done: today's file exists under briefs/, first 5 lines match that order.
• Stops: never.
• Resumes: not applicable.
• If it fails: class transient on a write failure, escalate if it

repeats.

• Built today, partially. engine/daily.py writes the brief every run.

Phase 0, in progress: today's opening lines are new-sources, assets-ready,

scheduled, due-today, not the five spec'd lines. Telegram delivery is not wired.

Stage 20: Sleep

• Starts: Report is done.
• Does: 1. Write controls/heartbeat with this run's timestamp.

1. Exit cleanly. 3. Let launchd fire the next run, 07:15 or 15:15.

• Done: controls/heartbeat's timestamp matches this run's completion.
• Stops: not applicable, this is the end of the pass.
• Resumes: the next scheduled launchd fire.
• If it fails: if it never reaches Sleep, the heartbeat file goes stale

and a separate watcher pages after 1.5 intervals. See heartbeat_missing

in Part B.

• Phase 0, in progress. controls/heartbeat does not exist yet. The last

=== daily run end === line in logs/daily.log is the closest thing today.

---

PART B: THE HUMAN'S SOP

Only ever act here on an open exception. Everything else runs unattended.

needs_human: account:\<lane\>

• You see: Telegram, "NEEDS YOU: no \ account for \."

Mission Control card under "What needs a human."

• Do: 1. Create a social account in that lane, Entertainment, Podcasts,

or Gaming. Phone and a human required, no way around it. 2. Register:

python3 -c "import sys;sys.path.insert(0,'engine');import accounts;accounts.add('','','')".

1. Tell Clara the handle, platform, lane.

• Resolves: automatically, once Stage 5's next pass finds and assigns it.

needs_human: rules_doc

• You see: Telegram, "NEEDS YOU: rules doc unreachable, \."

Mission Control card with campaign and marketplace.

• Do: 1. Open the campaign's page on its marketplace. 2. Copy its

rules or allowed-content document URL. 3. Paste it into the exception in

Mission Control, or tell Clara.

• Resolves: automatically, once Stage 3 re-runs with the URL on file.

publish_failed / "publish requires a Claude session"

• You see: Telegram, "NEEDS YOU: N posts due, no publish path." Mission

Control card listing each post: account, platform, file, hook.

• Do, option A: open a Claude session on the Mac, say "publish

due." It uses the Higgsfield MCP tools to post each queued clip.

• Do, option B: post the clip yourself from the app, paste the URL

back into the queue row.

• Resolves: automatically, once a URL is recorded, Stage 13 confirms it next pass.

submit not capable

• You see: Telegram, "NEEDS YOU: submit \, URL ready." Mission

Control card with the post URL and campaign.

• Do: 1. Open the campaign on its marketplace. 2. Paste the URL

into its submit form. 3. Mark it done in Mission Control, or tell Clara.

• Resolves: you close it, marking submitted sets the post's submitted field.

payout_late

• You see: Telegram, "payout late, \, N days past its own

estimate." Mission Control Money card, stated days vs elapsed.

• Do: nothing required. 3 of these on one marketplace flip its

reliability to bad automatically. Chasing it yourself is optional.

• Resolves: automatically, once payment lands, or the third occurrence flips the flag.

reconcile_mismatch

• You see: Telegram, "MISMATCH: \, platform $X, tracked $Y,

bank $Z." Mission Control shows all three on the campaign's Money card.

• Do: 1. Check the platform's earnings dashboard. 2. Check the

wallet or bank deposit. 3. Tell Clara which number is wrong, and why.

• Resolves: you close it, once the numbers agree within 5%, or you say

which to trust.

throttle_suspected (account paused)

• You see: Telegram, "\ paused, view velocity under 25% of its

own median for 2 days." Mission Control greys out the account.

• Do: 1. Leave it paused a few days, throttles usually lift on their

own. 2. If it doesn't recover, rebrand it to a different campaign in the

same lane: accounts.rebrand(handle, platform, new_campaign_id).

• Resolves: you close it, unpausing once velocity recovers, or after a rebrand.

llm_spend_cap

• You see: Telegram, "AI spend cap hit, $N today." Mission Control shows

it under The Engine.

• Do: nothing required. Moment scoring and hook writing pause for the day.

Discovery, tracking, reporting keep running. To spend more, raise the number

in controls/limits.json.

• Resolves: automatically, resets at midnight.

heartbeat_missing

• You see: Telegram, "NO HEARTBEAT since \, expected by \,"

from a separate watcher, since silence can't page on its own.

• Do: 1. Check the job is loaded: launchctl list | grep clipping.

1. Check the last run: tail -30 logs/daily.log. 3. Check today's

brief: cat briefs/$(date +%F).md. 4. Reload the plist if unloaded. If

ffmpeg, node, or yt-dlp is missing from PATH, read SYSTEM.md's PATH note

first, the plist PATH is pinned on purpose.

• Resolves: automatically, once a run completes and controls/heartbeat updates.

Controls, always available

• Pause everything: touch controls/KILL. Every stage with a side effect

stops. Discover, Score, Report keep running.

• Resume: rm controls/KILL.
• Leave test mode: rm controls/TEST_MODE, only once the Phase 1 gate

below is met, never before. 1. 3 consecutive clean sandbox days, zero

unknown-class exceptions. 2. At least one account past its cooldown.

1. Ralph has joined at least one campaign.

---

PART C: DAILY AND WEEKLY RHYTHM

The 07:15 brief's first five lines

#	Line	What it means	What you do

|---|---|---|---|

1	Money earned yesterday and to date	The only number that matters, long run	Nothing, if it moves up. Flat for days, check Stage 17's reliability flags
2	Open escalations	Count of unresolved exceptions	Zero, nothing to do. Above zero, go to Part B for the type named
3	Posts published / confirmed / submitted	Today's throughput	A gap between published and confirmed over a day flags a Stage 13 problem
4	Active campaigns and runway	The 3 to 5 selected, days of pool life left	Under 5 days, it parks itself. No action needed
5	Heartbeat time	Proof the loop ran	Not today's date, see `heartbeat_missing` in Part B

The weekly Learn output

Every week, Stage 17 recomputes reliability flags, refreshes the

historical-performance term, re-runs Stage 5's selector, and shifts experiment

allocation toward whichever hook style, caption style, or post time is

winning. Nothing is required of you. Worth a glance at Mission Control's

Strategy tab to see which arm won and why.

The monthly restore test

The nightly backup is tarred, kept 30 days, one copy off the machine. A

restore is tested once a month and logged. Nothing required, unless the log

shows a failed or skipped test, which is itself an exception to work.

---

PART D: PHASE GATES

Nothing skips a phase. A phase that regresses, an unknown exception, a

reconciliation miss, a paused account, drops back one phase until clean again.

Phase 0, Sandbox (now)

• [ ] Full loop runs in TEST MODE end to end: discover, verify, score,

allocate, ingest, analyze, render, QA, schedule, dry-run publish and submit,

track, reconcile on dry data, report.

• [ ] Heartbeat, backups, and kill switch all working.
• [ ] Mission Control is behind Cloudflare Access.

Evidence: dryrun/ has an entry for every would-be publish and submit.

controls/heartbeat updates twice a day. A restore-test log exists. Mission

Control requires a login.

Phase 1, First live post

Gate to enter:

• [ ] 3 consecutive clean sandbox days, zero unknown-class exceptions.
• [ ] At least one account past its 3-day cooldown.
• [ ] Ralph has joined at least one campaign.

What runs: one account, one campaign, one post a day, live publish via the

session path, submit via browser adapter or exception.

Stays human: joining campaigns. Publishing, if the headless-session test fails.

Evidence: audit/YYYY-MM-DD.jsonl shows 3 days with no unknown rows.

accounts.json shows an account aged 3 days or more. A campaign record shows

status: active.

Phase 2, Loop closed

Gate to enter:

• [ ] First payout reconciled within 5%.

What runs: both accounts, 3 campaigns, allowance-driven cadence,

experiments on.

Stays human: account creation, escalations only.

Evidence: a reconciliation record on disk with all three numbers, delta under 5%.

Phase 3, Scale

Gate to enter:

• [ ] 14 consecutive days of reconciled earnings.
• [ ] Exception count under 5% of posts.

What runs: add accounts and campaigns. Throughput follows the capacity

formula, the sum of each account's allowance for its warm-up stage.

Stays human: account creation, escalations only.

Evidence: 14 days of reconcile records on disk. Exception-to-post ratio

computed and under 5%.

---

PART E: DEFINITION OF DONE, PER STAGE

#	Stage	Done means, on disk

|---|---|---|

0	Health	Health record written, every dependency checked, kill switch state read
1	Discover	`last_seen` updated for every pollable marketplace this run
2	Sync	`burn_rate_per_day`, `runway_days`, `last_seen` current on every campaign
3	Verify	`approved_sources[]` populated, payout terms captured or marked unknown
4	Score	All 7 `score_parts` present, `score` and `eligible` written
5	Allocate	3 to 5 campaigns `selected` or `active`, each with an assigned account
6	Ingest	File on disk, checksum recorded, URL provably in `approved_sources[]`
7	Analyze	Timestamped moments with scores stored in the job's metadata
8	Render	mp4 exists, probe shows 1080x1920, duration in range, audio present
9	QA	Clip marked `qa_passed` with every check recorded, or `qa_failed` with the reason
10	Schedule	`queue.json` shows every asset `queued` with a slot, or `unplaced` with a reason
11	Pre-publish	Idempotency key written, all 4 gate checks passed, in `due_now.json`
12	Publish	Post id or URL recorded against the clip
13	Confirm	Post record shows `confirmed: true` with a readable view count
14	Submit	URL on file with the campaign, submission id or screenshot stored
15	Track	`metrics.json` shows updated `views` and `checked` for the post
16	Reconcile	Three numbers agree within 5%, or an open exception names the mismatch
17	Learn	`reliability` flags updated, new selection run logged
18	Cleanup	No source or clip file older than its retention window remains
19	Report	Today's brief exists, first 5 lines in the required order
20	Sleep	`controls/heartbeat` timestamp matches this run's completion