feat: start mailbox evidence scanner

docs/coordination-engine-email-spec-review.md

@@ -0,0 +1,46 @@
+# coordination-engine Email Spec Review
+
+## Source Specs
+
+Reviewed local coordination-engine specifications:
+
+- `/home/worsch/coordination-engine/spec/EmailAdapterSpecification.md`
+- `/home/worsch/coordination-engine/spec/AdapterInterfaceSpecification.md`
+- `/home/worsch/coordination-engine/spec/RuntimeArchitectureAndAdapterSubsystem.md`
+- `/home/worsch/coordination-engine/spec/ProductRequirementsDocument.md`
+
+These are referenced, not copied, so `email-connect` stays aligned with the
+authoritative coordination-engine checkout.
+
+## Contract Points For email-connect
+
+- `email-connect` is a `notification`, `communication`, and `interaction`
+  adapter.
+- It reports email-channel evidence and advisory assessment. It does not own
+  coordination case result evaluation.
+- Ambiguous provider or mailbox signals must map to the weakest safe normalized
+  event.
+- Provider and mailbox events must preserve raw references and native status
+  mappings.
+- The adapter must expose or enable production of normalized `EvidenceEvent`
+  records.
+- The adapter should expose endpoint quality diagnostics, but endpoint quality
+  is not coordination success.
+- Email's positive evidence ceiling is limited: email tracking cannot prove
+  human awareness, identity, authority, payload access, or non-repudiation.
+- Golden tests must include overclaim prevention, especially "provider
+  delivered" not becoming awareness or payload delivery.
+
+## First Implementation Implications
+
+- The mailbox scanner emits `EmailEvidenceCandidate` rows that are shaped to
+  become coordination-engine `EvidenceEvent` records later.
+- Classifiers preserve `unknown_return_message` and `parse_failed` instead of
+  silently discarding uncertainty.
+- Out-of-office replies update diagnostics only; they do not prove awareness or
+  reachability.
+- Human replies are email-channel success signals, but not legal acceptance or
+  coordination result satisfaction.
+- CSV reports include event type, assessment category/subclass, confidence,
+  evidence strength, observed time, occurred time, raw reference, and
+  deduplication key for auditability.