From 1475a5980a8061cd3ab8ed7fe918b3466732bc15 Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Mon, 16 Nov 2026 11:44:30 +0100 Subject: docs: design a rule that moves mail to spam or trash The rules dialog predates moves, so a rule can tag mail spam but leave it in the inbox folder. An optional move field names an account role, spam or trash, never a folder; the post-new hook moves on arrival, strips inbox and keeps unread. Item 214. Co-Authored-By: Claude Opus 5.5 --- .../plans/2026-08-03-post-0.1.0-usability.md | 19 ++++ .../specs/2026-11-16-rule-move-design.md | 120 +++++++++++++++++++++ 2 files changed, 139 insertions(+) create mode 100644 docs/superpowers/specs/2026-11-16-rule-move-design.md (limited to 'docs') diff --git a/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md b/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md index 6e36905..119f557 100644 --- a/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md +++ b/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md @@ -151,6 +151,7 @@ taking that too literally. | 211 | Archiving thousands of selected rows freezes the window | defect | S | **done** 2026-10-31, unreleased. Cubic optimistic-update path made linear: a lazily rebuilt id index in `ThreadListModel` and `MainWindow::batchModelWrites()` refreshing the action labels once per loop. A write now reads "applying…" until the worker has run it, then "done". Hand-tested on a 10158-message archive | | 212 | A rule edit reaches only new mail; applying it to the backlog is a hand-typed `notmuch tag` | workflow | M | open, designed: `specs/2026-10-31-rule-apply-and-archive-design.md` Part A. Apply saves, counts what would change, confirms with the count (a new documented exception to the no-confirmation rule), writes through `applyTags` for exact undo | | 213 | A rule removing `inbox` is skipped whole by the hook, so promo mail arrives untagged | defect | S-M | open, designed: same spec, Part B. Optional per-rule `allow_archive`, both readers, no version bump; `unread` stays refused; the dialog warns about rules the hook will skip | +| 214 | A rule can tag mail spam but cannot move it to the spam or trash folder | workflow | M | open, designed: `specs/2026-11-16-rule-move-design.md`. Optional `move` field, `spam` or `trash` (an account role, never a folder name), both readers, no version bump; the hook moves on arrival, strips `inbox`, keeps `unread`; Apply (212) inherits it later. First task: verify `notmuch new` can run inside `post-new` | | 73 | This backlog is past four thousand lines | maintenance | S | **done** 2026-08-13; 5056 lines to 578, closed sections moved to `2026-08-03-post-0.1.0-usability-closed.md` | | 74 | "Searching..." keeps claiming a query is running while rows are already arriving | feedback | XS | **done** 2026-08-15, unreleased. The status-bar half only: the bar now counts threads per batch. The cold-cache delay itself was measured in 2026-08-11 and is not fixable here | | 75 | The tagging rules window forgets its size and its column widths | persistence | S | **done** 2026-08-13, shipped in 0.17.0. The window-kind question is left open, see the closed-items file | @@ -1733,3 +1734,21 @@ applied without the removal. The rules dialog says nothing about it. **Constraints.** A rule-format change: both readers, both suites, and the hand round trip under "Changing the rule format". The hook runs every ten minutes on real mail. + +## 214. A rule cannot move mail to the spam or trash folder + +**Observed (user, 2026-11-16):** "the filters window doesn't allow to set +actions like 'move to spam folder'. It was built before we introduced the +moves in the code." + +**Cause.** Verified: a rule is `(add, remove, query, stage)` in both readers +(`TagRule` in `src/tagrules.h`, `KNOWN_KEYS` in `assets/hooks/mailrules.py`), +and the `post-new` hook only ever runs `notmuch tag`. The rules predate items +103 and 187, which made Delete and Mark spam move files. + +**Approach.** `specs/2026-11-16-rule-move-design.md`. + +**Constraints.** A rule-format change: both readers, both suites, and the hand +round trip under "Changing the rule format". The hook would now rename files +on real mail every ten minutes, and a wrong destination reaches the server +(item 103), so the destination is an account role, never a folder name. diff --git a/docs/superpowers/specs/2026-11-16-rule-move-design.md b/docs/superpowers/specs/2026-11-16-rule-move-design.md new file mode 100644 index 0000000..3c2999a --- /dev/null +++ b/docs/superpowers/specs/2026-11-16-rule-move-design.md @@ -0,0 +1,120 @@ +# A rule that moves mail to the spam or trash folder + +Item 214. Designed 2026-11-16. + +## Problem + +The rules dialog can only add and remove tags. It was built (item 44, +`2026-08-12-tagging-rules-design.md`) before Delete and Mark spam became file +MOVES (items 103 and 187), so a rule can tag a message `spam` but cannot put it +in the spam folder. The result is mail the rule recognised still sitting in the +inbox folder, and showing up under *Find stranded spam*. + +## Decisions made with the user + +1. **Destination is an account ROLE, never a folder name.** A rule says + `spam` or `trash`; each message goes to its OWN account's configured folder + for that role. A typed folder name is refused because a wrong one is created + by the move and propagated to the server (item 103). There is no `archive` + role: archive is a tag, not a folder. +2. **The move strips `inbox` and keeps `unread`.** `inbox` goes because a + message in the spam folder carrying it would still be listed by the Inbox + filter. `unread` stays because `maildir.synchronize_flags` is on and + removing it reaches the server; keeping it also lets the user see what a + rule caught. `PROTECTED_REMOVALS` is NOT relaxed: the `-inbox` is part of + the move, applied only to mail the move actually relocated, never to a + rule's `remove` list. +3. **On arrival only.** The `post-new` hook performs the move. Item 212's Apply + button (designed in `2026-10-31-rule-apply-and-archive-design.md`, unbuilt) + will honour `move` when it is built, by routing through the existing + `NotmuchWorker::moveMessages()` so the move gets undo. This item does not + build that. + +## Format + +One optional field on a rule: + +```json +{ "id": "known-spammers", "query": "from:example.org", "add": [], "remove": [], + "move": "spam" } +``` + +- Values: `"spam"` or `"trash"`. Absent or empty means no move. +- Optional field, so **no `kFormatVersion` / `FORMAT_VERSION` bump.** +- Both readers change (`src/tagrules.cpp`, `assets/hooks/mailrules.py`) and both + drop it from `unknown` handling by knowing it. +- The "adds and removes nothing" check becomes "adds, removes and moves + nothing": a move-only rule is valid. +- An unknown value is an invalid rule in `TagRules::validate()` (the dialog + cannot write one). The Python reader logs it and ignores the `move` while + still applying the rule's tags, since the tags are harmless and the hook must + never guess a destination. + +## Hook + +After all tag stages have run, and BEFORE `tag:new` is consumed: + +1. For each enabled rule with a `move`, in stage order, collect message ids + matching `tag:new and ()`. A message claimed by an earlier rule is + not reclaimed; the conflict is logged naming both rules. +2. For each claimed message, resolve each of its files to an account by path + (the same prefix logic `qtmaildirconf` already uses) and that account's + `spam` or `trash` key. `qtmaildirconf` gains a reader for those two keys. +3. Skip, with a log line, a message whose account has no folder for the role, + and a file already in the destination folder. Never invent a folder. +4. Rename the file into `///cur/` under a + FRESH name (no `,U=` infix, item 162; port `MaildirName::fresh()`, keeping + the flags suffix). `cur/`, never `new/`. Record the origin folder before the + rename, as `moveMessages()` does. +5. After all renames, run ONE `notmuch new --no-hooks` so notmuch records each + rename against the existing message id, keeping its tags. +6. Then tag the relocated ids: `+moved-from:` (one per origin folder, + same tag format the app writes and Restore reads), `+spam` for the spam + role, and `-inbox`. Do not touch `unread`. + +### Failure + +- A failed rename leaves that message where it was, logged; the others proceed. +- A failed `notmuch new --no-hooks` or `notmuch tag` returns failure from the + hook, so `tag:new` is NOT consumed (the existing safety rule). The next run + sees the files already in the destination and only re-tags. + +### To verify first (plan task 1) + +That `notmuch new --no-hooks` can run from inside `post-new`, i.e. the outer +`notmuch new` has released the write lock when it calls the hook, and that a +renamed file with a known id keeps its tags and gets no `new.tags`. Measure it +on a throwaway database. If it fails, the fallback is to defer moves to a step +in `assets/mailsync.sh` after `notmuch new` returns; the rest of this design is +unchanged. + +## Dialog + +A **Move to** combo under the remove field: *Don't move*, *Spam folder*, *Trash +folder* (labels translated; the stored value is the wire-format role, per the +"translating a string something matches on" rule). When an account in the +config has no folder for the chosen role, a warning line under the combo names +it, since the hook will skip that account's mail. + +## Unchanged + +- Restore and Not spam read `moved-from:` and work as they do for a manual move. +- A hook move has no undo, like every other hook tag. +- No version bump, no new dependency. + +## Tests + +- `assets/hooks/`: a real move over a throwaway Maildir: fresh name in `cur/`, + tags survive, `moved-from:` written, `-inbox`, `unread` kept, `+spam` only + for the spam role, missing role skipped, two rules claiming one message, a + file already in place left alone, and `tag:new` kept on a failing step. +- `test_tagrules`: `move` round-trips, an unknown value fails `validate()`, a + move-only rule is valid, and a file written by Python with `move` survives a + C++ save. +- The hand round trip under "Changing the rule format" in `AGENTS.md`. + +## Out of scope + +- Applying a move to existing mail (item 212 will). +- Moves to arbitrary folders. +- Relaxing `unread`. -- cgit v1.2.3