docs: add ADR workflow and update skills

- 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>

docs/adr/0001-imap-thread-resolution.md

@@ -0,0 +1,35 @@
+---
+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.

docs/adr/README.md

@@ -0,0 +1,75 @@
+# Architecture Decision Records
+
+This directory contains Architecture Decision Records (ADRs) for durable technical decisions in this repository.
+
+## Purpose
+
+ADRs capture cross-cutting or behavior-defining decisions that future contributors need to preserve.
+
+Use an ADR when a change introduces or locks in a decision such as:
+
+- runtime behavior that future work must preserve
+- repository-wide technical policy
+- architecture or integration contracts
+- storage or threading semantics
+- quality gate or workflow policy
+
+Do not use ADRs for:
+
+- temporary implementation plans
+- agent execution checklists
+- one-off debugging notes
+- PR-local task breakdowns
+
+## Format
+
+Each ADR is a markdown file with YAML frontmatter.
+
+```md
+---
+type: ADR
+id: "NNNN"
+title: "Short decision title"
+status: active
+date: YYYY-MM-DD
+---
+
+## Context
+
+Why does this decision need to exist now?
+
+## Decision
+
+**State the decision clearly in one or two sentences.**
+
+## Options considered
+
+- **Option A** (chosen): description with pros and cons
+- **Option B**: description with pros and cons
+- **Option C**: description with pros and cons
+
+## Consequences
+
+What becomes easier?
+What becomes harder?
+What risks were accepted?
+What would trigger re-evaluation?
+
+## Advice
+
+Optional. Capture important external input or review notes.
+```
+
+## Rules
+
+- One decision per file.
+- Name files `NNNN-short-kebab-title.md`.
+- Once active, do not rewrite an ADR's meaning later. Supersede it with a new ADR instead.
+- Keep the index below aligned with the current files in this directory.
+- Do not keep placeholder or mock entries in the index.
+
+## Index
+
+| ID | Title | Status |
+|----|-------|--------|
+| 0001 | IMAP thread resolution prefers In-Reply-To and falls back to References | active |