outreach-ledger

# Outreach Ledger Give a project a nervous system for its in-flight conversations: a ledger of every thread, due-touch flags, and optional read-only inbox polling. The system observes and reminds; humans draft and send. **Reference implementation ships in this folder**: `outreach.mjs` (ledger + CLI), `outreach-poll.mjs` (read-only IMAP poller with reply AND bounce detection), `seed.example.json`. Copy and adapt rather than reinvent. Requires node; `npm install` in this folder pulls the two dependencies (better-sqlite3, imapflow). ## Recipe 1. **Scope the threads.** List every conversation the project has in flight: who, org, email (if known), channel, current state, what was last sent and when. Ask the user to confirm the list — seeds are facts, not guesses. 2. **Ledger table** in the project's existing store (SQLite via `outreach.mjs`, or a markdown/JSON ledger for code-free projects): target, org, email, thread_subject, channel, status (`drafted → sent → replied → in_conversation → terms_sent → signed → dormant → closed`, plus `bounced` as a dead-end — rename states to fit the domain), doctrine, dates, touch_count, notes. Seed idempotently (re-running the seed must add nothing). 3. **CLI or checklist**: `--list` (grouped by status), `--touch <id>` (update state + next date), `--due` (rows where next_touch_at ≤ today, each with a suggested action). 4. **Due-action wording matters**: warm/personal relationships → "human touch due — nudge the user, no draft"; cold/transactional sends → "day-N follow-up due — draft with approval". Third un-replied touch → suggest marking dormant. 5. **Inbox poller (optional, needs mailbox creds in a gitignored .env)**: IMAP scan since last-seen UID; store the UID cursor. Two reconciliations, both mandatory: - **Reply**: a From match on a watched address → flip to `replied`, surface an alert. - **Bounce**: a delivery-status/NDR from `mailer-daemon`/`postmaster` → parse the failed recipient from the body and flip that row to `bounced`. Without it, a dead address sits at `sent` forever, indistinguishable from awaiting-reply — the precise failure this skill exists to kill. A reply-only poller is not "working fully". Read-only per the hard rules below. ## Hard rules (do not soften) - **No auto-send code path exists, anywhere.** The ledger flags; drafting happens with the user; the user approves every outbound. Do not build a "send follow-up" function even behind a flag. - **Respect the project's contact doctrine.** Some threads must never be nudged (a client who comes to you; a relationship where chasing costs more than silence). Set `doctrine: "no-chase"` — tracked in `--list`, structurally excluded from `--due`. - **Poller is read-only** — open folders read-only, touch no flags, unread stays unread. - **Bounces are a state, not a silence.** The poller must detect NDRs and mark the row `bounced`; a dead address masquerading as awaiting-reply defeats the whole ledger. - **Credentials** live in the project's gitignored env file, never committed, never echoed. ## Verify before finishing Run the seed twice (second run = 0 changes). Run `--due` and sanity-check the suggested actions against the doctrine rules. If a poller was wired: one `--once` run against the real inbox, confirm it reports without mutating (a message's unread state must survive), and confirm a bounce flips its row to `bounced` (send one deliberately-bad-address test, or check a past NDR is caught) — not just that replies flip to `replied`.