Create canonical wiki page Repo docs CAMPAIGN DELIVERY RUNBOOK

Repo-docs-CAMPAIGN-DELIVERY-RUNBOOK.md

@@ -0,0 +1,84 @@
+<!-- codex-wiki-sync:cb6acffba8b788d578627d6c -->
+
+> Mirrored from `/mnt/DATA/git/govoplan-campaign/docs/CAMPAIGN_DELIVERY_RUNBOOK.md`.
+> Origin: `repository`.
+> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
+
+---
+# Campaign Delivery Runbook
+
+This runbook covers controlled campaign delivery after a campaign version has
+been validated, built, reviewed, and locked.
+
+## Operating Modes
+
+- Local direct send: `CELERY_ENABLED=false`. Queueing stores jobs in the DB, and
+  small development runs can be processed with "Send queued now".
+- Worker send: `CELERY_ENABLED=true` with Redis/Celery workers running. Queueing
+  publishes delivery tasks, and the Review & Send page polls summary counters.
+- Mock send: use only for development review. It does not prove real SMTP/IMAP
+  credentials or server policy.
+
+## Before First Live Use
+
+- Use dedicated non-production SMTP/IMAP credentials.
+- Use a dedicated mailbox/folder for append-to-Sent tests.
+- Confirm policy allows the SMTP host, envelope sender, recipients, and optional
+  IMAP append target.
+- Run one campaign each for no attachment, one attachment, and password-protected
+  ZIP before using production recipients.
+- Keep the report page open during tests; it is the operational source of truth
+  for attempts, outcomes, and reconciliation.
+
+## Queue And Send
+
+1. Validate the version with file checks enabled.
+2. Build the version and inspect all blocking review items.
+3. Queue only after the selected version is the intended immutable execution
+   version.
+4. In local mode, use "Send queued now" for small test runs.
+5. In worker mode, verify queue counters move from queued/claimed/sending to a
+   terminal SMTP state.
+
+## Outcome Handling
+
+- `smtp_accepted`: Do not retry. If IMAP append is enabled and pending, run or
+  enqueue the append action.
+- `failed_temporary`: Retry explicitly after checking the error and retry count.
+- `failed_permanent`: Retry only if the operator has corrected the root cause and
+  intentionally includes permanent failures.
+- `outcome_unknown`: Do not retry directly. Check SMTP logs, mailbox evidence, or
+  provider control panels, then reconcile as accepted or not sent.
+- `claimed` or `sending` that does not progress: treat as a worker interruption.
+  Re-run worker handling or reconcile if SMTP may already have accepted the
+  message.
+
+## Reconciliation
+
+- Choose "Accepted" only with external evidence that SMTP accepted the message.
+  The job becomes protected from retry and may proceed to IMAP append.
+- Choose "Not sent" only when SMTP did not accept the message. The job becomes a
+  temporary failure and can be selected by explicit retry.
+- Add a note that identifies the evidence used, for example SMTP log line,
+  provider message ID, or operator ticket.
+
+## Fault Injection Checklist
+
+Use mock infrastructure first, then repeat against the non-production real test
+bed where possible:
+
+- SMTP temporary failure.
+- SMTP permanent failure.
+- Recipient refusal after partial SMTP acceptance.
+- Connection drop or worker interruption during SMTP.
+- IMAP append failure after SMTP acceptance.
+- Worker restart with queued, claimed, and sending jobs.
+
+## Reporting Checks
+
+- Partial delivery must show accepted, failed, and unknown counts separately.
+- Accepted and unknown jobs must not appear in retry selections.
+- Reconciled accepted jobs must remain protected from resend.
+- Reconciled not-sent jobs must appear only as explicit retry candidates.
+- The final report should include SMTP attempts, IMAP append attempts, and any
+  reconciliation notes before the campaign is considered operationally closed.