generated from coulomb/repo-seed
357 lines
10 KiB
Markdown
357 lines
10 KiB
Markdown
---
|
|
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.
|