feat(mail): draft to Gmail or a local Maildir, set per project; setup proposes mail backends

[potiuk]

Summary

• Maildir is now a real drafting backend. The security skills that draft mail (issue-import, issue-invalidate, issue-sync including the GHSA relay, cve-allocate) can now file their drafts into a local Maildir that Thunderbird or another mail client shows, as well as into Gmail. On Maildir they thread by In-Reply-To / References on the inbound Message-ID (PonyMail supplies it, or the root the tracker records). Before filing, they check for a draft already waiting with the new read-only maildir-draft-find. Before this, the Maildir tool existed but no skill could use it.
• The drafting backend is set per project, and each person can override it. The project sets mail_create.backend in project.md; a person sets tools.mail_create in their own user.md. The rule is user.md, then project.md, then gmail, defined once in tools/gmail/draft-backends.md, which every draft site already links.
• setup config proposes mail backends. Before this, config never mentioned them. For an ASF project, PonyMail and apache-projects are selected by default. The drafting choice is written to the project's configuration, or as a personal override in user.md once the user has seen the lines. Every install step (install.md 9c, 9d, 9e) now ends with a numbered what to do next list: run the commands, restart the agent, authenticate, verify. It says the claude.ai Gmail connector stays connected for reading only. Thunderbird's Repair Folder is documented for a draft that doesn't show up.

Type of change

• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Tool / bridge contract (tools/<system>/*.md)
• Python package (tools/*/ with pyproject.toml)
• Project template (projects/_template/)

Test plan

• prek run --all-files passes
• For Python packages touched: tools/maildir ruff, mypy and pytest pass (17 tests, 8 new for maildir-draft-find, including ~ expansion and bare Message-IDs)
• For skill changes: new suites setup/step-config-mail 7/7 and security-issue-sync/step-draft-backend 5/5; re-run against the edited sections: setup/step-config-adversarial 5/5, setup/step-config-stamp 6/6, security-issue-import/step-0-preflight 3/3, security-issue-import/step-7-apply 3/3, security-issue-invalidate/step-5d-email-draft 2/2, security-issue-sync/step-ghsa-access-tier 5/5, security-cve-allocate/step-4-propose-updates 3/3. Self-eval only (Claude Code, Opus 5.5).
• For skill behaviour changes: new eval fixtures included (12 cases across the two new suites)
• Second read: roborev (codex, then gemini). Every finding was fixed in this PR: an apache-projects gap in the hand-over, the missing Gmail read path, Maildir offered but not wired up (the reason for the security-skill changes), ~ expansion, Message-ID parsing, and an empty-subject match. The last gemini pass on the branch is a Pass.

RFC-AI-0004 compliance

• HITL — config writes a personal user.md override only after showing the lines; every MCP registration is printed for the user to run, never run by the agent
• Vendor neutrality — drafting no longer requires Gmail; Maildir needs no account, credential or network
• Write-access discipline — both drafting backends create drafts only; nothing is sent

Linked issues

None.

Notes for reviewers (optional)

• tools/spec-loop/specs/adoption-and-setup.md (criterion 32) and adapters.md (criterion 6) describe the new behaviour. .last-sync is left where it was: it is 55 commits behind main for reasons unrelated to this PR, and bumping it here would claim those commits are synced.
• Draft recap lines and the "Gmail draft ID" wording in the skills' recap sections still say Gmail; the Maildir recipe in draft-backends.md defines its own recap line.

---

Generative AI disclosure: drafted with Claude Code (Opus 5.5) and reviewed by the author.

🤖 Generated with Claude Code