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>
36 lines
2.2 KiB
Markdown
36 lines
2.2 KiB
Markdown
---
|
|
type: ADR
|
|
id: "0001"
|
|
title: "IMAP thread resolution prefers In-Reply-To and falls back to References"
|
|
status: active
|
|
date: 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-To` first, then `References` last-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 omit `In-Reply-To`.
|
|
- **Search `References` from 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.
|