thuanleandClaude Opus 4.7
b013c68988
- Add docs/adr/README.md with ADR format, rules, and index - Add ADR-0001: IMAP thread resolution via In-Reply-To + References - Add Documentation Rules section to AGENT.md - Update validate-issue skill: flag ADR-requiring changes - Rename do-task → implement-task for clearer semantics - Update review-pr skill: accept docs/adr/, reject agent artifacts Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2.2 KiB
type, id, title, status, date
| type | id | title | status | date |
|---|---|---|---|---|
| ADR | 0001 | IMAP thread resolution prefers In-Reply-To and falls back to References | active | 2026-04-28 |
Context
The IMAP ingress flow stores a thread_id before dispatching work to OpenClaw. Previously the bridge only used In-Reply-To to find a parent task. Some valid email clients preserve thread ancestry through References even when In-Reply-To is absent. In those cases, the bridge created a new thread_id, which broke conversation continuity and downstream session reuse.
This decision needs to be durable because future refactors of mail parsing, dispatch, or storage must preserve the same thread-resolution behavior.
Decision
The bridge resolves parent thread linkage by trying In-Reply-To first. If no parent task is found, it falls back to References, scanning message IDs from last to first and using the first match found in the database. If neither header yields a known parent, the message's own message_id becomes the new thread_id.
Options considered
- Use
In-Reply-Tofirst, thenReferenceslast-to-first (chosen): preserves existing behavior, matches common email ancestry ordering, and favors the most recent known parent. - Use only
In-Reply-To: simpler, but breaks valid threads when clients omitIn-Reply-To. - Search
Referencesfrom first to last: may attach to an older ancestor even when a more recent known parent exists. - Normalize all thread linkage into a more complex conversation graph: more flexible, but out of scope for the current bridge behavior.
Consequences
Thread continuity is improved for replies that rely on References.
Future contributors have an explicit behavioral contract for threading semantics.
Mail parsing changes must preserve the header precedence and reverse scan behavior unless a new ADR supersedes this one.
The current approach still depends on existing message IDs being present in the database; if upstream behavior changes significantly, this decision may need reevaluation.
Advice
If a future change wants different precedence rules or deeper conversation reconstruction, create a new ADR rather than silently changing this behavior.