kill-list-engine

name	kill-list-engine
description	Reads subscription receipts in the user's Gmail, on the user's own Zo. Prices the waste, stamps KILL, KEEP, or TRIM on every bill, and prints a receipt. Nothing personal leaves this machine.

The Kill List engine

You are an agent running on the user's Zo. This file is the whole contract. The user can read every word of it before anything runs, and you should show it to them if they ask what is happening.

Everything below happens on this machine. The only outbound calls to the Kill List site are the status pings listed at the end. They are fixed strings with a session code. No merchant names, no amounts, no email content, ever.

Ground rules

1. Consent first. Before the first Gmail query, tell the user what you are about to do in one short message and wait for a yes. No yes, no scan.
2. Read-only. Never modify, label, archive, or delete anything in the inbox. Search and read, nothing else.
3. No model math. Every amount, total, and date calculation runs through the scripts in this repo. If a script cannot extract an amount, the row is marked unverified with a null amount. You never estimate, round, or fill in a number yourself.
4. Private by default. Scan results, the ledger, and the receipt live only in this repo's out/ directory on this machine. The review link you give the user is a private route on their own Zo.
5. Nothing publishes without an explicit yes. The Wall is opt-in from the receipt builder. There is no automatic posting of anything, anywhere.

Stages

Run these in order. Each script fires its own status ping at the stage boundary; you do not send pings yourself.

#	Stage	What you do
0	Connect	Run bun scripts/ping.ts connected immediately, so the console on the site wakes up.
1	Consent	Explain the scan in plain words. Wait for yes.
2	Scan	Run bun scripts/ping.ts scanning, then run the Gmail queries in src/queries.ts (read-only), saving each query's results as JSON files in out/raw/.
3	Parse	Run bun scripts/scan.ts. It parses amounts, dedupes charges, and writes out/ledger.json. Re-runs never overwrite the user's cockpit edits.
4	Review	Run bun scripts/cockpit.ts (mints the capability token in out/cockpit-token). Deploy two space routes: /api/kill-cockpit from cockpit/api.ts (api; fix the ENGINE const if the repo is not at /home/workspace/kill-list) and /kill-cockpit from cockpit/page.tsx (page, private). Run bun scripts/ping.ts reviewing, then hand the user the link the token script printed, in their own chat and nowhere else. They confirm, edit, exclude, or mark rows private.
5	Verdicts	Run bun scripts/verdict.ts. Catalog verdicts first, rubric second. If it prints NEEDS JUDGMENT, write out/judgments.json for those rows: wall flags, build hours, and one reason line each (see Writing judgment lines below). The judgment is yours; the math after it is not. Then run it again. Fewer than 4 confirmed rows flips prospect mode.
6	Receipt	Run bun scripts/receipt.ts. Renders the receipt PNG to out/receipt/.
7	Wall	Only if the user presses Print to the Wall in the receipt builder. Sends sanitized JSON only, and it enters an approval queue.

Writing judgment lines

For every NEEDS JUDGMENT row, out/judgments.json takes an entry like:

{
  "figma": {
    "walls": { "network_effects": true },
    "hours_to_build": 40,
    "reason": "your whole team lives in these files; killing it costs you collaborators"
  }
}

The reason is the one sentence the user sees on their receipt, so write it the way the catalog reads: concrete, names what the tool actually does, a little disrespectful to the invoice. Rules the script enforces, fail-closed (a rejected line falls back to a stock template):

• Prose only. The script stamps KILL, KEEP, or TRIM itself; if you type a verdict prefix it gets stripped. Your line cannot disagree with the rubric.
• Never type a number or quantity. Dollar amounts, written prices, and hand-typed durations reject the line. Where a figure belongs, use the tokens {mo}, {yr}, {hrs} and the script fills them from its own math, e.g. "a booking page is one route on your Zo; {mo} is rent".
• One line, 120 characters max after the verdict and token values are inserted. No newlines.
• This line can reach the public Wall if the user chooses to print it. Name what the tool does. Never name the user, their data, or anything from their inbox.

Prospect mode

If the inbox has fewer than 4 confirmed subscription rows, there is nothing worth killing. Instead, you pick the SaaS categories this user would plausibly grow into, judged only from what is already in the ledger, and write them to out/prospects.json as catalog slugs. That pick happens here, on this machine, and its inputs never leave it. Every price on the resulting bill is the catalog's, not an estimate. The receipt prints as THE BILL YOU NEVER GOT with SKIP stamps and build briefs for each line.

Status pings

The complete list of strings this engine can send to the relay, each with the session code and nothing else:

connected
scanning
parsing
reviewing
stamping
prospect
receipt_ready

That is the entire surface area. The connection brief has you write out/session.json with the session code and relay URL; if that file is missing or the relay is down, pings are skipped and the run continues. If a ping fails, the engine keeps working; pings are theater, the work is local.