---
id: EMAIL-WP-0001
type: workplan
title: "Repository Onboarding and Implementation Foundation"
domain: custodian
repo: email-connect
status: finished
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: done
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: done
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: done
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.