Epic: Trustworthy single-account MailPlus Intelligence roadmap

[jmcte]

Objective

Turn MailPlus Intelligence from a fixture-mode reference implementation into a trustworthy single-account product while preserving the canonical-store boundary: MailPlus owns raw mail; this repository owns metadata, reviewed derived intelligence, and source locators.

This epic is the execution plan produced from the July 2026 project audit. It intentionally prioritizes release truth, data integrity, privacy, and a complete read-only vertical slice before relationship graphs, web UI, multi-account support, or autonomous actions.

Product decision

The near-term target is a single-account, read-only MailPlus alpha:

1. Incrementally sync metadata from one live account.
2. Reconstruct and search correspondence reliably.
3. Fetch exact source content only through an explicit, operator-selected transient boundary.
4. Produce evidence-backed candidates.
5. Require human review before any durable export.
6. Keep live mailbox mutation and automatic reminders out of scope.

Metadata-only sync remains the default. If transient source fetch is not accepted, the product promise must be narrowed to metadata search and triage; commitment and decision extraction cannot be reliable from subject/sender metadata alone.

Delivery phases

Phase A — Trust and safety recovery release

Exit criteria:

• Installed wheel can initialize and migrate a database.
• Sync cannot advance a checkpoint after a partial or rejected record.
• The fixture evaluation harness is green and enforced in CI.
• Promotion provenance and review history are complete and auditable.
• Selected-text expiration actually disposes of text.
• Public PR CI has a documented safe runner boundary.
• Operator docs are executable and agree with runtime behavior.
• A verified patch release supersedes the broken v0.1.0 release without moving its public tag.

Phase B — Single-account read-only alpha

Exit criteria:

• A credential-gated MailPlus/IMAP adapter can run a real metadata sync.
• Cursor semantics handle mailbox identity and invalidation safely.
• Updates, moves, deletions, replay, and locator history have defined behavior.
• Operators can search a correspondent across sender and recipient roles.
• mpi doctor distinguishes configured, reachable, authenticated, and sync-capable.
• No live exporter or mailbox mutation is enabled.

Phase C — Semantic alpha

Exit criteria:

• Operator-selected source fetch is transient, minimized/redacted, and audited.
• Extraction preserves source message IDs, locators, evidence, model/rule version, and review state.
• A review cockpit supports approve, reject, defer, correct, and rollback-needed transitions.
• One local Markdown/JSON exporter is idempotent and reversible.
• Cloud model egress is explicit, configurable, and disabled by default.

Product features after the vertical slice

• mpi history person@example.com
• commitments and unanswered-follow-up inbox
• daily review digest
• source-locator deep links
• configurable VIP/project/lane rules
• evidence-centered review explanations

Deferred work

Do not start these until the read-only and semantic alpha exit criteria are met:

• relationship graph
• multi-account support
• web UI
• streaming LLM extraction
• remote wiki/task/calendar integrations
• automatic reminders or mailbox actions

Engineering definition of done

Every child issue must include:

• behavior-focused tests, including failure and replay paths
• privacy review for any stored or logged mail-derived field
• exact local validation commands and results
• docs updated in the same change when a public/operator contract changes
• installed-artifact proof for packaging or release work
• no checkpoint, promotion, or external write on partial failure
• a PR that links and closes the child issue

Execution order

Phase A — parallel recovery lane

These issues are ready to start immediately and can proceed in parallel, with schema coordination between #100, #102, and #103:

• Make sync writes and checkpoint advancement atomic #100 — atomic sync writes, reject handling, and checkpoint advancement
• Repair the fixture evaluator and make semantic regression a CI gate #101 — repair evaluator and make regression a CI gate
• Preserve complete semantic provenance and add append-only review auditing #102 — complete semantic provenance and append-only review auditing
• Enforce selected-text disposal and explicit model-egress privacy controls #103 — selected-text disposal and model-egress privacy controls
• Harden public PR CI, secrets, action pinning, and dependency maintenance #104 — public PR CI, secrets, action pinning, and dependency maintenance
• Make CLI, doctor, and operator documentation an executable contract #105 — executable CLI, doctor, and operator documentation contract
• Package migrations, add installed-wheel smoke tests, and prepare v0.1.1 #99 — package migrations and installed-wheel validation (implementation may proceed now)

Phase A merge/release gate: the packaging portion of #99 can land independently, but the v0.1.1 publication portion is blocked until #100–#105 are closed and their required checks are green.

Phase B — read-only alpha lane

• Wire normalization, thread reconstruction, suppression, and reconciliation into one ingest pipeline #107 — unified ingest, threading, suppression, and reconciliation; starts after Make sync writes and checkpoint advancement atomic #100, with schema coordination from Preserve complete semantic provenance and add append-only review auditing #102
• Implement one credential-gated read-only MailPlus/IMAP sync loop #106 — real read-only MailPlus/IMAP sync loop; starts after Make sync writes and checkpoint advancement atomic #100, Harden public PR CI, secrets, action pinning, and dependency maintenance #104, and Make CLI, doctor, and operator documentation an executable contract #105
• Complete correspondent search and add an evidence-backed history command #108 — correspondent search and mpi history; implementation starts after Wire normalization, thread reconstruction, suppression, and reconciliation into one ingest pipeline #107, though query/API design may proceed earlier

#106 and #107 are intended to run in parallel once their gates are satisfied. Phase B is complete only when first sync, resume, replay, correspondent history, and doctor capability checks pass without live export or mailbox mutation.

Phase C — semantic alpha lane

• Implement an operator-selected transient source-fetch boundary #109 — operator-selected transient source fetch; implementation is blocked on Preserve complete semantic provenance and add append-only review auditing #102, Enforce selected-text disposal and explicit model-egress privacy controls #103, Implement one credential-gated read-only MailPlus/IMAP sync loop #106, and Wire normalization, thread reconstruction, suppression, and reconciliation into one ingest pipeline #107

Parallel-safety rules

• Coordinate migrations across Make sync writes and checkpoint advancement atomic #100, Preserve complete semantic provenance and add append-only review auditing #102, and Enforce selected-text disposal and explicit model-egress privacy controls #103 before merging.
• Do not duplicate thread, locator, or participant rules between Implement one credential-gated read-only MailPlus/IMAP sync loop #106, Wire normalization, thread reconstruction, suppression, and reconciliation into one ingest pipeline #107, and Complete correspondent search and add an evidence-backed history command #108.
• Do not introduce a second artifact/provenance model outside Preserve complete semantic provenance and add append-only review auditing #102.
• Do not introduce source-text persistence outside the policy implemented by Enforce selected-text disposal and explicit model-egress privacy controls #103.
• Update this checklist when a child PR closes an issue.

Agent claim and handoff protocol

1. Confirm all listed dependencies are closed or explicitly limit work to interface/test preparation.
2. Comment on the child issue with the intended implementation slice and expected files before editing.
3. Keep one coherent PR per child issue unless the issue explicitly documents a split.
4. Link the issue in the PR and include exact validation commands/results.
5. Update the issue checklist or leave a closing summary when behavior, tests, docs, and installed/runtime proof are complete.
6. Do not mark a task complete from unit tests alone when the issue requires installed-artifact, concurrency, privacy, or live/fake-server evidence.

Audit baseline

• Repository: OMT-Global/mailplus-intelligence
• Audited ref: origin/main@23999b5
• Fast unit suite: 133 passing tests
• Documented evaluator: classification 0/40, semantic 0/1, suppression 0/0
• Current open issues/PRs at epic creation: none
• Current product state: fixture-mode prototype; live adapter and live export are stubs