Skip to content

R4: Honest scope docs, CHANGELOG, and integration guides for stubbed surfaces #85

@jmcte

Description

@jmcte

Goal

Set correct expectations about what v0.1.0 ships and what is intentionally stubbed, so external users understand the scope without filing false bug reports against the live adapter or production exporter.

This is R4 of six release milestones (R1–R6) leading to v0.1.0.

Evidence

  • src/mailplus_intelligence/live_adapter.py:80–85_fetch_messages is a stub returning [].
  • src/mailplus_intelligence/exporters.py enforces dry_run=True and rejects live writes.
  • pyproject.toml:7 — version 0.1.0 with no changelog or release-history file.
  • README.md describes the long-term architecture but does not call out which pieces are stubbed in v0.1.

Acceptance criteria

Scope statement in README

  • New "What's in v0.1" section in README.md immediately after the architecture overview, with two subsections:
    • Working end-to-end: fixture-mode sync, schema, threading, classification, suppression, deterministic extraction, LLM extraction (with [llm] extra), promotion queue, dry-run exporters, scheduler, CLI, doctor.
    • Stubbed / not-yet-wired: live MailPlus/IMAP adapter (returns empty batches), production export to wiki/memory//reminders (dry-run only).
  • Each stubbed item links to its integration guide (below) and the issue tracking the live work.

Integration guides

  • docs/integration/live-mailplus-adapter.md — what live_adapter.py expects, the env vars, the SyncBatch shape that _fetch_messages must return, and a worked example of a third-party stub talking to a generic IMAP server. Marked as "v0.2 territory; PRs welcome".
  • docs/integration/live-export.md — what an exporter that promotes to wiki / memory/ / reminders needs to honor (provenance, rollback, idempotency), referencing docs/promotion-review-workflow.md. Marked as "v0.2 territory".

Changelog and versioning policy

  • New CHANGELOG.md (Keep-a-Changelog format) with an ## [Unreleased] header and a populated ## [0.1.0] - YYYY-MM-DD section listing the closed M0–M5 milestones at a feature level (not commit level).
  • New docs/versioning.md (or a section in CONTRIBUTING.md) stating the semver policy: 0.x means breaking changes within minor versions are allowed but documented.
  • Single source of truth for the version: pyproject.toml, exposed via mailplus_intelligence.__version__ (sourced from importlib.metadata). README and quickstart reference it from there, not duplicated.

Cross-references

Out of scope

  • Actually implementing the live adapter or live exporters (those are post-v0.1 epics). This issue only documents them.

Definition of done

  • All boxes checked.
  • A reader of the public README can answer "should I expect live MailPlus to work?" within 30 seconds (answer: not yet, here's the plan).

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions