diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..99bd4f8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,188 @@ +# email-connect — Agent Instructions + +## Repo Identity + +**Purpose:** Headless, provider-neutral email communication and evidence service +for sending, tracking, diagnosing, and normalizing email-channel events without +overclaiming delivery, awareness, or result satisfaction. + +**Domain:** custodian +**Repo slug:** email-connect +**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a` +**Workplan prefix:** `EMAIL-WP-` + +--- + +## Repo Orientation + +This repository is currently in planning/specification shape. Treat +`INTENT.md` as the canonical product intent and +`spec/ProductRequirementsDocument.md` as the detailed requirements source until +implementation architecture is added. + +Preserve the core principle: email events are evidence, not result +satisfaction. Provider acceptance, MX acceptance, inbox placement, opens, +clicks, replies, complaints, suppressions, and bounces must remain distinct. +Do not collapse them into "delivered", "read", "accepted", or any similar +business conclusion. + +Keep the product provider-neutral and adapter-friendly. It should be useful as +a standalone email communication/evidence service and as the reference +`coordination-engine` adapter. It should not drift into newsletter campaign +management, broad marketing automation, or legal/business outcome adjudication. + +There is no runtime stack committed yet. Any stack, API, storage, or provider +choice should be introduced through a workplan and anchored in the current +intent/PRD. + +--- + +## State Hub Integration + +The Custodian State Hub tracks work across all domains. Interact via HTTP REST — +there is no MCP server for Codex agents. + +| Context | URL | +|---------|-----| +| Local workstation | `http://127.0.0.1:8000` | +| Remote via tunnel | `http://127.0.0.1:18000` | + +### Orient at session start + +```bash +# Offline brief, when present +test -f .custodian-brief.md && cat .custodian-brief.md + +# Active workstreams for this domain +curl -s "http://127.0.0.1:8000/workstreams/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \ + | python3 -m json.tool + +# Check inbox +curl -s "http://127.0.0.1:8000/messages/?to_agent=email-connect&unread_only=true" \ + | python3 -m json.tool +``` + +Mark a message read: +```bash +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' +``` + +### Log progress (required at session close) + +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{ + "summary": "what was done", + "event_type": "note", + "author": "codex", + "workstream_id": "", + "task_id": "" + }' +``` + +Omit `workstream_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"status": "progress"}' +# values: wait | todo | progress | done | cancel +``` + +### Flag a task for human review + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"needs_human": true, "intervention_note": "reason"}' +``` + +--- + +## Session Protocol + +**Start:** +1. `test -f .custodian-brief.md && cat .custodian-brief.md` — domain goal and open workstreams, when present +2. Check inbox: `GET /messages/?to_agent=email-connect&unread_only=true`; mark read +3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks +4. Check human-needed tasks: `GET /tasks/?needs_human=true` + +**During work:** +- Update task statuses in workplan files as tasks progress +- Record significant decisions via `POST /decisions/` + +**Close:** +1. Update workplan file task statuses to reflect progress +2. Log: `POST /progress/` with a summary of what changed +3. Note for the custodian operator: after workplan file changes, run from + `~/state-hub`: + ```bash + make fix-consistency REPO=email-connect + ``` + This syncs task status from files into the hub DB. + +--- + +## Workplan Convention (ADR-001) + +Work items originate as files in this repo — not in the hub. The hub is a +read/cache/index layer that rebuilds from files. + +**File location:** `workplans/EMAIL-WP-NNNN-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-EMAIL-WP-NNNN-.md`. The `YYMMDD` prefix is +the completion/archive date; the frontmatter `id` does not change. + +**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use +`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use +this only for low-risk work completed directly; create a normal workplan for +anything needing analysis, design, approval, dependencies, or multiple phases. + +**Frontmatter:** + +```yaml +--- +id: EMAIL-WP-NNNN +type: workplan +title: "..." +domain: custodian +repo: email-connect +status: proposed | ready | active | blocked | backlog | finished | archived +owner: codex +topic_slug: ... +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +state_hub_workstream_id: "" # written by fix-consistency — do not edit +--- +``` + +Use `proposed` for a new draft, `ready` after review against current repo +state, and `finished` after implementation. `stalled` and `needs_review` are +derived health labels, not frontmatter statuses. + +**Task block format** (one per `##` section): + +``` +## Task Title + +` ` `task +id: EMAIL-WP-NNNN-T01 +status: wait | todo | progress | done | cancel +priority: high | medium | low +state_hub_task_id: "" # written by fix-consistency — do not edit +` ` ` + +Task description text. +``` + +Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. + +To create a new workplan: +1. Write the file following the format above +2. Notify the custodian operator to run `make fix-consistency REPO=email-connect` + (or send a message to the hub agent via `POST /messages/`) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..cece215 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,20 @@ +# email-connect - Claude Code Instructions + +This repository uses `AGENTS.md` as the canonical local agent instruction file. +Claude Code agents should read `AGENTS.md` first and follow the same State Hub +identity, workplan convention, and repo-specific semantic guardrails. + +State Hub identity: + +- Domain: `custodian` +- Repo slug: `email-connect` +- Topic ID: `cee7bedf-2b48-46ef-8601-006474f2ad7a` +- Workplan prefix: `EMAIL-WP-` + +Core product rule: email events are evidence, not result satisfaction. Do not +treat provider acceptance, MX acceptance, inbox placement, opens, clicks, +replies, complaints, or suppressions as proof of human awareness or business +outcome completion. + +Start with `INTENT.md`, then `spec/ProductRequirementsDocument.md`, then the +active files under `workplans/`. diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..99cbd03 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,140 @@ +# SCOPE + +## One-liner + +`email-connect` is a headless, provider-neutral email communication and +evidence service for sending, tracking, diagnosing, and normalizing email +events. + +--- + +## Core Idea + +Email is useful evidence, but it is not proof of human awareness or business +result satisfaction. This repository exists to model email as an uncertain +communication channel: preserve raw provider events, normalize email-native +facts, classify weak or suspicious engagement signals conservatively, and emit +coordination-compatible evidence for downstream orchestration. + +The product should be useful both as a standalone operational email service and +as the first reference adapter for `coordination-engine`. + +--- + +## In Scope + +- Provider-neutral transactional and notification email send API. +- Message, attempt, raw event, and timeline records. +- Provider webhook/event ingestion and native status mapping. +- Normalized email evidence events for coordination workflows. +- Bounce, deferral, complaint, unsubscribe, and suppression handling. +- Endpoint quality signals for email addresses and recipient endpoints. +- Conservative open, click, reply, scanner, proxy, and privacy classification. +- Adapter descriptor, capability profile, evidence ceiling, and health reporting. +- Generic APIs and future UI surfaces for operators, support teams, agents, and developers. + +--- + +## Out of Scope + +- Newsletter campaign management or broad marketing automation. +- Claiming inbox placement, human reading, authenticated recipient action, or legal acceptance from email telemetry alone. +- Evaluating whether the intended business result was satisfied; that belongs to `coordination-engine`. +- Becoming a provider-specific dashboard clone. +- Owning non-email communication channels. + +--- + +## Relevant When + +- A system needs to send transactional or coordination-related email without binding directly to one provider. +- Operators need to inspect what happened to a message across provider, MX, bounce, suppression, open, click, and reply events. +- Agents or services need queryable email-channel evidence with explicit uncertainty. +- `coordination-engine` needs an email adapter that emits normalized evidence events and declares evidence ceilings. + +--- + +## Not Relevant When + +- The goal is bulk marketing, newsletter design, campaign segmentation, or growth automation. +- The system needs proof of recipient awareness, legal acceptance, or business outcome completion. +- A single provider dashboard is sufficient and provider-neutral modeling is unnecessary. +- The work is about another notification channel such as SMS, push, chat, or postal mail. + +--- + +## Current State + +- Status: concept / planning +- Implementation: intent and PRD only +- Stability: evolving +- Usage: none yet + +The repository currently contains product intent and requirements. No runtime +stack, API implementation, persistence model, provider integration, or UI has +been committed yet. + +--- + +## How It Fits + +- Upstream dependencies: email providers, provider webhooks, adapter interface expectations, coordination evidence vocabulary. +- Downstream consumers: `coordination-engine`, automation agents, product systems, operators, support users, audit/compliance reviewers. +- Often used with: State Hub workplans, future `coordination-engine` adapter contracts, provider-specific email integrations. + +--- + +## Terminology + +- Preferred terms: email evidence, message timeline, provider acceptance, MX acceptance, deferral, hard bounce, soft bounce, suppression, complaint, privacy open, scanner click, unverified interaction, evidence ceiling. +- Also known as: email adapter, email evidence service, provider-neutral email layer. +- Potentially confusing terms: "delivered" must be decomposed into provider/MX facts; "opened" must not imply human reading; "clicked" must not imply authenticated recipient action. + +--- + +## Related / Overlapping + +- `coordination-engine` - expected downstream evaluator of intended results and consumer of normalized email evidence. +- `llm-connect` - sibling `*-connect` style adapter/service pattern in the custodian domain. +- `state-hub` - tracks repo registration, workplans, progress, and consistency for this repository. + +--- + +## Getting Oriented + +- Start with: `INTENT.md`. +- Key files / directories: `spec/ProductRequirementsDocument.md`, `workplans/`, `AGENTS.md`. +- Entry points: no code entry points yet. + +--- + +## Provided Capabilities + +```capability +type: service +title: Provider-neutral email communication +description: Send transactional and coordination-related email through a stable provider-neutral interface while preserving provider-specific evidence for diagnosis. +keywords: [email, transactional-email, notification, provider-neutral, communication] +``` + +```capability +type: evidence +title: Email event normalization +description: Normalize raw provider events into conservative email-channel evidence, distinguishing acceptance, deferral, bounce, suppression, complaint, open, click, and reply signals. +keywords: [email, evidence, normalization, bounce, suppression, tracking] +``` + +```capability +type: adapter +title: coordination-engine email adapter +description: Provide the adapter descriptor, capability profile, evidence ceiling, health reporting, and normalized evidence events needed by coordination-engine. +keywords: [coordination-engine, adapter, evidence-ceiling, notification, email] +``` + +--- + +## Notes + +The core product discipline is semantic restraint: report what the email channel +knows, preserve uncertainty, and leave result evaluation to downstream +coordination logic. diff --git a/workplans/EMAIL-WP-0001-repo-onboarding.md b/workplans/EMAIL-WP-0001-repo-onboarding.md new file mode 100644 index 0000000..7c34290 --- /dev/null +++ b/workplans/EMAIL-WP-0001-repo-onboarding.md @@ -0,0 +1,124 @@ +--- +id: EMAIL-WP-0001 +type: workplan +title: "Repository Onboarding and Implementation Foundation" +domain: custodian +repo: email-connect +status: active +owner: codex +topic_slug: custodian +created: "2026-06-02" +updated: "2026-06-02" +state_hub_workstream_id: "4533ceb6-bd86-49ee-a014-cffd68f84fbb" +--- + +# EMAIL-WP-0001 - Repository Onboarding and Implementation Foundation + +## Goal + +Bring `email-connect` from intent and PRD into an implementation-ready, +State-Hub-indexed repository while preserving the product's semantic guardrail: +email events are evidence, not result satisfaction. + +## Context + +The repository currently contains product intent and a product requirements +document. It is registered under the `custodian` domain because its primary +strategic role is to serve as a provider-neutral email evidence service and the +reference `coordination-engine` adapter for email. + +This workplan covers repository onboarding and the first implementation +foundation. It should not choose a runtime stack or provider-specific design +without first recording the architecture rationale. + +## T01 - Complete State Hub Registration Artifacts + +```task +id: EMAIL-WP-0001-T01 +status: done +priority: high +state_hub_task_id: "f3c64208-b8da-45c3-88cf-e1be7ed51e72" +``` + +Register the repo with State Hub and add the local coordination files needed by +future agents. + +Done when: + +- the State Hub repo record has domain, local path, host path, remote URL, + fingerprint, description, and topic ID; +- `AGENTS.md` describes the repo identity and State Hub workflow; +- `SCOPE.md` declares scope boundaries and provided capabilities; +- `.custodian-brief.md` is generated by consistency sync. + +## T02 - Define The Initial Runtime Architecture + +```task +id: EMAIL-WP-0001-T02 +status: todo +priority: high +state_hub_task_id: "fdfd8b96-7326-414f-8126-79bb3a21b950" +``` + +Select and document the first implementation architecture. + +The architecture note should cover: + +- API shape and first service boundaries; +- persistence model for messages, attempts, raw events, timelines, suppressions, + and endpoint quality; +- provider abstraction boundaries; +- webhook ingestion and event authenticity checks; +- how normalized email evidence maps into `coordination-engine`; +- local development, test, and migration commands. + +## T03 - Model The Email Evidence Canon + +```task +id: EMAIL-WP-0001-T03 +status: todo +priority: high +state_hub_task_id: "ef1eb769-dfa0-4b46-8633-274d90962423" +``` + +Turn the intent/PRD evidence distinctions into a concrete domain model. + +The model should distinguish at least: + +- provider acceptance; +- recipient MX acceptance; +- temporary deferral; +- hard and soft bounce; +- provider drop; +- suppression; +- complaint and unsubscribe; +- privacy/proxy open; +- scanner or bot click; +- unverified click; +- human-like reply; +- out-of-office response. + +Done when the model explicitly prevents treating technical delivery, open, or +click telemetry as proof of human awareness or result satisfaction. + +## T04 - Create The First Service Skeleton + +```task +id: EMAIL-WP-0001-T04 +status: todo +priority: medium +state_hub_task_id: "4b94e544-5aad-4c38-8fe3-eed17af79971" +``` + +Create the initial code skeleton after T02 and T03 have enough shape to avoid a +throwaway implementation. + +Expected first slice: + +- package/module layout; +- configuration loading; +- health/status endpoint or CLI equivalent; +- test harness; +- placeholder provider interface; +- first message/timeline domain objects; +- README update with actual development commands.