coulomb/email-connect
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add expected recipient reporting workplan

Browse Source
This commit is contained in:
Bernd Worsch
2026-06-02 02:45:33 +02:00
parent 7a9686f53a
commit 5ea6c738d2
1 changed files with 356 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

356
workplans/EMAIL-WP-0003-expected-recipient-reporting-and-mailbox-tutorial.md Normal file
View File

@@ -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.