diff --git a/workplans/EMAIL-WP-0003-expected-recipient-reporting-and-mailbox-tutorial.md b/workplans/EMAIL-WP-0003-expected-recipient-reporting-and-mailbox-tutorial.md new file mode 100644 index 0000000..df08f9e --- /dev/null +++ b/workplans/EMAIL-WP-0003-expected-recipient-reporting-and-mailbox-tutorial.md @@ -0,0 +1,356 @@ +--- +id: EMAIL-WP-0003 +type: workplan +title: "Expected Recipient Reporting and Mailbox Tutorial" +domain: custodian +repo: email-connect +status: active +owner: codex +topic_slug: custodian +created: "2026-06-02" +updated: "2026-06-02" +state_hub_workstream_id: "438149d2-4f20-42b1-91fd-cdeff29dec7d" +--- + +# EMAIL-WP-0003 - Expected Recipient Reporting and Mailbox Tutorial + +## 1. Purpose + +This workplan extends the mailbox evidence scanner so operators can provide an +optional set of target email addresses that were expected to receive +notifications. When expected recipients are provided, the scanner should include +them in the evidence report even when no mailbox evidence is known for a given +recipient. + +The result is a report that can answer both: + +```text +What evidence did the mailbox contain? +Which expected recipients have no known email-channel evidence? +``` + +The scanner must continue to work without a target-recipient list. Email events +remain evidence, not proof of delivery, awareness, or coordination success. + +## 2. User Story + +As an operator, I want to provide a line-separated list or CSV file of email +addresses that were supposed to receive notifications, scan a mailbox for return +evidence within a chosen time range, and generate a report where expected +recipients are easy to filter and appear before incidental mailbox-only +addresses. + +## 3. In Scope + +The workplan shall support: + +- Optional expected-recipient input from a newline-separated text file. +- Optional expected-recipient input from CSV. +- CLI and config support for recipient list paths. +- Email address normalization and deduplication. +- Reports that can be generated without any expected-recipient input. +- Reports that include expected recipients with no known evidence. +- An explicit `known_recipient` boolean column in the report. +- Default report ordering with known recipients first. +- An `undef` evidence/report row for expected recipients where nothing is known. +- Mail inspection limited to a datetime range. +- Excluding all email evidence from messages outside the configured range. +- Tests that prove no overclaiming occurs for unknown expected recipients. +- A tutorial for generating a mailbox report from configuration through output + review. + +## 4. Out of Scope + +The workplan does not require: + +- Outbound sending. +- Proving that all provided expected recipients were actually contacted. +- Requiring expected recipients for report generation. +- Legal delivery assessment. +- A suppression-management UI. +- Multi-mailbox correlation. +- Cross-batch campaign management. + +## 5. Report Semantics + +Expected recipients are advisory context supplied by the operator. If an +expected recipient has no evidence rows, the scanner should emit a conservative +unknown row: + +```text +event_type: diagnostic.expected_recipient.no_evidence +assessment_category: undef +assessment_subclass: undef.no_signal +evidence_strength: none +known_recipient: true +``` + +This row means only: + +```text +The recipient was supplied as an expected notification target, and this scan +found no mailbox evidence for that address in the inspected time range. +``` + +It must not mean: + +```text +delivery failed +delivery succeeded +recipient was not notified +recipient ignored the message +``` + +Mailbox-only evidence rows for addresses not in the supplied expected-recipient +set should remain visible with: + +```text +known_recipient: false +``` + +If no expected-recipient input is provided, the report should still be generated +from mailbox evidence only and `known_recipient` should default to `false`. + +## 6. Time Range Semantics + +The scanner should support an optional inclusive datetime range: + +```text +--from 2026-06-01T00:00:00Z +--to 2026-06-02T23:59:59Z +``` + +Messages outside the range must be excluded before parsing and evidence +generation whenever the message timestamp is available. The range should also be +usable from config. If a message has no parseable timestamp, the implementation +should either include it with a diagnostic note or exclude it only when the +behavior is explicitly documented and tested. + +Existing `--since` behavior may be retained as a compatibility alias for the +lower bound, but the new range should be expressed clearly in documentation. + +## 7. CLI Target + +Example commands: + +```text +email-connect scan-mailbox --config config/mailbox.yml --out reports/ +email-connect scan-mailbox --config config/mailbox.yml --expected-recipients recipients.txt --out reports/ +email-connect scan-mailbox --config config/mailbox.yml --expected-recipients recipients.csv --expected-recipient-column email --out reports/ +email-connect scan-mailbox --config config/mailbox.yml --from 2026-06-01T00:00:00Z --to 2026-06-02T23:59:59Z --out reports/ +``` + +## 8. Work Packages + +## T01 - Expected Recipient Input Model + +```task +id: EMAIL-WP-0003-T01 +status: todo +priority: high +state_hub_task_id: "d1cd0de0-cbd5-4e8d-8179-000ba10e5506" +``` + +Tasks: + +```text +Add expected-recipient config fields +Add CLI option for expected-recipient file path +Support newline-separated email address files +Support CSV files with configurable email column +Normalize addresses case-insensitively +Deduplicate recipient addresses +Reject or warn on invalid addresses without aborting the scan +``` + +Acceptance: + +```text +The scanner can load zero, one, or many expected recipients from text or CSV. +Invalid recipient rows are visible as warnings or diagnostics. +``` + +## T02 - Known Recipient Report Column and Ordering + +```task +id: EMAIL-WP-0003-T02 +status: todo +priority: high +state_hub_task_id: "3d7d3bb8-4118-4158-b874-b4e0527eaa85" +``` + +Tasks: + +```text +Add known_recipient boolean column to CSV reports +Mark evidence rows true when affected_email_address matches expected recipients +Mark mailbox-only rows false when no expected list is provided or no match exists +Sort report rows with known recipients first by default +Preserve deterministic secondary sorting +Document filtering behavior for spreadsheet users +``` + +Acceptance: + +```text +Generated reports include known_recipient and place known-recipient rows before +unknown-recipient rows by default. +``` + +## T03 - No-Evidence Rows for Expected Recipients + +```task +id: EMAIL-WP-0003-T03 +status: todo +priority: high +state_hub_task_id: "aa737837-2f19-4fbf-9920-f98413bd9779" +``` + +Tasks: + +```text +Detect expected recipients with no matching evidence in the inspected range +Generate diagnostic.expected_recipient.no_evidence rows for those recipients +Use assessment_category undef +Use assessment_subclass undef.no_signal +Use evidence_strength none +Avoid endpoint-quality updates from no-evidence rows +Avoid implying delivery failure or delivery success +Deduplicate generated no-evidence rows across rescans +``` + +Acceptance: + +```text +Expected recipients with no mailbox evidence appear in the report as undef +no-signal diagnostics, not as failures or successes. +``` + +## T04 - Optional Recipient Context + +```task +id: EMAIL-WP-0003-T04 +status: todo +priority: medium +state_hub_task_id: "731cf592-1bbe-4143-b21b-721af281528c" +``` + +Tasks: + +```text +Keep report generation working when no recipient list is provided +Keep report generation working when recipient list is empty +Ensure expected-recipient input is not required for mailbox-only reports +Ensure mailbox-only evidence remains visible even when expected recipients are provided +``` + +Acceptance: + +```text +Reports can be generated with no expected recipients, empty expected recipients, +or partial expected recipients. +``` + +## T05 - Datetime Range Filtering + +```task +id: EMAIL-WP-0003-T05 +status: todo +priority: high +state_hub_task_id: "22585e83-d995-42d9-9ab2-c383b055fbb8" +``` + +Tasks: + +```text +Add config fields for scan datetime lower and upper bounds +Add CLI options for datetime lower and upper bounds +Treat --since as a compatibility alias for the lower bound +Exclude messages outside the configured range from parsing and evidence generation +Define behavior for messages with no parseable Date header +Apply filtering consistently to fixture and IMAP scans +Store the range on MailboxScan +Add tests for inclusive lower and upper bounds +``` + +Acceptance: + +```text +When a datetime range is configured, the scanner inspects only messages whose +message timestamp falls within the range according to the documented rules. +``` + +## T06 - Report and Evidence Tests + +```task +id: EMAIL-WP-0003-T06 +status: todo +priority: high +state_hub_task_id: "f30cd5b9-5035-42b4-9eca-a104e2b26ecb" +``` + +Tasks: + +```text +Add text recipient-list fixture +Add CSV recipient-list fixture +Add tests for known_recipient true and false rows +Add tests for known-recipient-first ordering +Add tests for no-evidence undef rows +Add tests that no-evidence rows do not update endpoint quality +Add tests for report generation with no recipient input +Add tests for datetime range exclusion +``` + +Acceptance: + +```text +Automated tests prove expected-recipient reporting, optional recipient input, +and datetime range filtering. +``` + +## T07 - Mailbox Report Tutorial + +```task +id: EMAIL-WP-0003-T07 +status: todo +priority: medium +state_hub_task_id: "00a29cb9-ac5a-4784-a9c4-7f2d4905405c" +``` + +Tasks: + +```text +Create a tutorial for configuring mailbox access +Show fixture-based dry run +Show live IMAP configuration +Show expected-recipient text list usage +Show expected-recipient CSV usage +Show datetime range usage +Explain known_recipient filtering +Explain undef no-signal rows +Explain evidence limitations and overclaim prevention +Include troubleshooting notes for credentials and empty reports +``` + +Acceptance: + +```text +A new user can follow the tutorial to generate and interpret an email-connect +mailbox evidence report. +``` + +## 9. Completion Criteria + +This workplan is complete when: + +1. Expected-recipient input is optional and supports text and CSV files. +2. Reports include `known_recipient`. +3. Known recipients sort first by default. +4. Expected recipients with no evidence produce `undef.no_signal` diagnostic + rows. +5. The scanner still works without any expected recipients. +6. Datetime range filtering excludes messages outside the inspected range. +7. Tests cover recipient input, report ordering, no-evidence rows, optional + input, and datetime range filtering. +8. A tutorial documents how to generate a mailbox evidence report.