aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/superpowers/plans/2026-11-16-rule-move.md987
-rw-r--r--docs/superpowers/specs/2026-11-16-rule-move-design.md67
2 files changed, 1031 insertions, 23 deletions
diff --git a/docs/superpowers/plans/2026-11-16-rule-move.md b/docs/superpowers/plans/2026-11-16-rule-move.md
new file mode 100644
index 0000000..4e43280
--- /dev/null
+++ b/docs/superpowers/plans/2026-11-16-rule-move.md
@@ -0,0 +1,987 @@
+# Rule move to spam or trash: implementation plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** A tagging rule can carry `"move": "spam" | "trash"`, and the `post-new` hook moves matching new mail into each message's own account's folder for that role.
+
+**Architecture:** One optional field in `rules.json`, known to both readers (`src/tagrules.cpp`, `assets/hooks/mailrules.py`). The hook gains a move step after the tag stages: rename into `<account>/<folder>/cur/` under a fresh name, one `notmuch new --no-hooks` to record the renames, then tag. The dialog gains a *Move to* combo. Spec: `docs/superpowers/specs/2026-11-16-rule-move-design.md`.
+
+**Tech Stack:** Python 3 stdlib (hook), Qt 6 / C++ (`TagRules`, `TagRulesDialog`), notmuch CLI.
+
+---
+
+## Before anything: work in a worktree
+
+The live notmuch `database.hook_dir` SYMLINKS into this repo's `assets/hooks/`,
+so an edit to `post-new` in the main checkout runs on the user's real mail at
+the next sync, ten minutes away at most. Every task below happens in a
+worktree, never in `~/Programming/GIT/qtmaildir` itself:
+
+```bash
+cd ~/Programming/GIT/qtmaildir
+git worktree add ../qtmaildir-rule-move -b rule-move
+cd ../qtmaildir-rule-move
+cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug && cmake --build build
+```
+
+All paths below are relative to that worktree.
+
+**No commits until the user's verdict.** The user's standing rule: hand the
+change back and wait. Tasks end at "suite green", not at a commit. Task 7 is
+the hand-over; the commit and merge come after the user says so.
+
+**Never run a test binary without `QT_QPA_PLATFORM=offscreen`.**
+
+---
+
+### Task 1: `qtmaildirconf.role_folders()`
+
+**Files:**
+- Modify: `assets/hooks/qtmaildirconf.py` (after `not_arrival_query`)
+- Test: `assets/hooks/test_qtmaildirconf.py`
+
+- [ ] **Step 1: Write the failing tests** (before `def main():`)
+
+```python
+def test_role_folders_pair_each_account_with_its_folder():
+ with tempfile.TemporaryDirectory() as tmp:
+ path = write_config(tmp,
+ "[account.one]\nmaildir = acct-one\nspam = Spam\ntrash = Trash\n"
+ "[account.two]\nmaildir = acct-two\nspam = [Provider]/Spam\n")
+ assert qtmaildirconf.role_folders("spam", path) == [
+ ("acct-one", "Spam"), ("acct-two", "[Provider]/Spam")]
+ # acct-two names no trash folder, so it contributes nothing rather
+ # than a guess the hook would then create on the server.
+ assert qtmaildirconf.role_folders("trash", path) == [
+ ("acct-one", "Trash")]
+
+
+def test_role_folders_need_a_maildir():
+ with tempfile.TemporaryDirectory() as tmp:
+ path = write_config(tmp, "[account.one]\nspam = Spam\n")
+ assert qtmaildirconf.role_folders("spam", path) == []
+```
+
+`write_config(tmp, text)` returns the path it wrote, and `main()` collects
+every `test_` function.
+
+- [ ] **Step 2: Run, expect FAIL** (`AttributeError: ... role_folders`)
+
+Run: `cd assets/hooks && ./test_qtmaildirconf.py`
+
+- [ ] **Step 3: Implement** (append to `qtmaildirconf.py`)
+
+```python
+# The folders a rule may MOVE mail into, by role. A rule names a role, never a
+# folder: a folder name that does not exist is created by the move and reaches
+# the server (item 103), and a role resolves per account, so one rule serves
+# mail from every account.
+MOVE_ROLES = ("spam", "trash")
+
+
+def role_folders(role, path=None):
+ """Every account's (maildir, folder) pair for a move role.
+
+ An account contributes nothing unless it names both its maildir and a
+ folder for the role. `spam` and `trash` are mandatory to the application,
+ which warns about a missing one; here a missing one just means that
+ account's mail is not moved.
+ """
+ if path is None:
+ path = default_path()
+
+ pairs = []
+ for _key, section in _accounts(path):
+ maildir = section.get("maildir", "").strip()
+ folder = section.get(role, "").strip()
+ if maildir and folder:
+ pairs.append((maildir, folder))
+ return pairs
+```
+
+- [ ] **Step 4: Run, expect all pass**
+
+Run: `cd assets/hooks && ./test_qtmaildirconf.py`
+
+---
+
+### Task 2: `move` in `mailrules.py`
+
+**Files:**
+- Modify: `assets/hooks/mailrules.py` (`KNOWN_KEYS`, `Rule`, `_rule_to_dict`, `_parse_rule`)
+- Test: `assets/hooks/test_mailrules.py`
+
+- [ ] **Step 1: Write the failing tests** (before `def run_all():`)
+
+```python
+def test_a_move_rule_loads_and_round_trips():
+ with tempfile.TemporaryDirectory() as tmp:
+ path = write_rules(tmp, {"version": 1, "rules": [
+ {"id": "junk", "query": "from:spammer@example.net",
+ "move": "spam"}]})
+ store = mailrules.load(path)
+ assert store.warnings == [], store.warnings
+ # A move-only rule is a rule: it adds and removes nothing.
+ assert [r.id for r in store.rules] == ["junk"]
+ assert store.rules[0].move == "spam"
+ assert "move" not in store.rules[0].unknown
+ mailrules.save(store, path)
+ assert json.loads(path.read_text())["rules"][0]["move"] == "spam"
+
+
+def test_a_rule_without_a_move_writes_no_move_key():
+ """Absent stays absent. Writing `"move": ""` on every rule would rewrite
+ every file either reader saves, a diff nobody made."""
+ with tempfile.TemporaryDirectory() as tmp:
+ path = write_rules(tmp, {"version": 1, "rules": [
+ {"id": "x", "add": ["x"], "query": "from:a@example.com"}]})
+ mailrules.save(mailrules.load(path), path)
+ assert "move" not in json.loads(path.read_text())["rules"][0]
+
+
+def test_an_unknown_move_role_is_ignored_and_the_tags_still_apply():
+ """The hook must never guess a destination, and must not lose the rule's
+ harmless tagging over it either."""
+ with tempfile.TemporaryDirectory() as tmp:
+ path = write_rules(tmp, {"version": 1, "rules": [
+ {"id": "odd", "add": ["x"], "query": "from:a@example.com",
+ "move": "Archive"}]})
+ store = mailrules.load(path)
+ assert store.rules[0].move == ""
+ assert store.rules[0].add == ["x"]
+ assert len(store.warnings) == 1 and "Archive" in store.warnings[0]
+
+
+def test_a_rule_whose_only_action_is_a_bad_move_is_dropped():
+ with tempfile.TemporaryDirectory() as tmp:
+ path = write_rules(tmp, {"version": 1, "rules": [
+ {"id": "odd", "query": "from:a@example.com", "move": "archive"}]})
+ store = mailrules.load(path)
+ assert store.rules == []
+ assert len(store.warnings) == 2, store.warnings
+```
+
+- [ ] **Step 2: Run, expect FAIL**
+
+Run: `cd assets/hooks && ./test_mailrules.py`
+
+- [ ] **Step 3: Implement**
+
+`KNOWN_KEYS`:
+
+```python
+KNOWN_KEYS = {"id", "stage", "enabled", "add", "remove", "query", "note",
+ "move"}
+
+# What `move` may say. Mirrors qtmaildirconf.MOVE_ROLES and the C++ reader;
+# see "Changing the rule format" in AGENTS.md.
+MOVE_ROLES = ("spam", "trash")
+```
+
+`Rule` dataclass, after `remove`:
+
+```python
+ move: str = ""
+```
+
+`_rule_to_dict`, after building `out` and before `out.update(rule.unknown)`:
+
+```python
+ # Only when set, so a file with no moves is byte-identical after a save.
+ if rule.move:
+ out["move"] = rule.move
+```
+
+`_parse_rule`, replacing the `add`/`remove` emptiness check:
+
+```python
+ add = [t for t in obj.get("add", []) if isinstance(t, str) and t.strip()]
+ remove = [t for t in obj.get("remove", []) if isinstance(t, str) and t.strip()]
+
+ move = obj.get("move", "")
+ if move and move not in MOVE_ROLES:
+ warnings.append(
+ f"rule '{rule_id}': move '{move}' is not spam or trash; "
+ f"ignoring the move")
+ move = ""
+
+ if not add and not remove and not move:
+ warnings.append(
+ f"rule '{rule_id}': adds, removes and moves nothing; dropped")
+ return None
+```
+
+and pass `move=move,` in the `Rule(...)` constructor.
+
+- [ ] **Step 4: Run, expect all pass** (including the pre-existing `test_a_bad_rule_is_dropped_and_the_rest_survive`, which checks ids, not the message text)
+
+Run: `cd assets/hooks && ./test_mailrules.py`
+
+---
+
+### Task 3: the hook moves
+
+**Files:**
+- Modify: `assets/hooks/post-new`
+- Test: `assets/hooks/test_post_new.py`
+
+- [ ] **Step 1: Write the nesting test FIRST** (before `def run_all():`), with its fixture
+
+```python
+import shutil # add to the imports at the top
+
+
+def setup_move(tmp):
+ """Two accounts with spam folders, one also with a trash folder, and
+ mail from a spammer in both inboxes beside one real message.
+
+ Account two names no trash folder on purpose: a trash rule must leave its
+ mail alone rather than invent one.
+ """
+ root = Path(tmp) / "Mail"
+ for sub in ("acct-one/Inbox", "acct-one/Spam", "acct-one/Trash",
+ "acct-two/Inbox", "acct-two/[Provider]/Spam"):
+ for part in ("new", "cur", "tmp"):
+ (root / sub / part).mkdir(parents=True)
+
+ make_message(root / "acct-one/Inbox", "junk-one",
+ "spammer@example.net", "buy now")
+ make_message(root / "acct-one/Inbox", "keep-one",
+ "friend@example.org", "hello")
+ make_message(root / "acct-two/Inbox", "junk-two",
+ "spammer@example.net", "buy again")
+
+ config = Path(tmp) / "notmuch-config"
+ config.write_text(
+ f"[database]\npath={root}\n\n"
+ f"[new]\ntags=new;unread;inbox\n\n"
+ f"[user]\nname=Test\nprimary_email=you@example.org\n")
+
+ env = dict(os.environ)
+ env["NOTMUCH_CONFIG"] = str(config)
+ env["XDG_CONFIG_HOME"] = str(Path(tmp) / "config")
+
+ conf = Path(env["XDG_CONFIG_HOME"]) / "qtmaildir" / "qtmaildir.conf"
+ conf.parent.mkdir(parents=True)
+ conf.write_text(
+ "[account.one]\nmaildir = acct-one\nspam = Spam\ntrash = Trash\n"
+ "[account.two]\nmaildir = acct-two\nspam = [Provider]/Spam\n")
+
+ subprocess.run(["notmuch", "new"], env=env, capture_output=True,
+ check=True)
+ return env, root
+
+
+SPAM_RULE = {"id": "junk", "query": "from:spammer@example.net",
+ "move": "spam"}
+
+
+def names(folder):
+ return sorted(p.name for p in folder.iterdir())
+
+
+def test_the_hook_can_move_when_notmuch_new_itself_runs_it():
+ """The design's one unverified assumption: that `notmuch new --no-hooks`
+ can run INSIDE post-new, because the outer `notmuch new` has released the
+ write lock by the time it calls the hook. Every other test runs the hook
+ directly and cannot see this. If it fails, stop: the fallback (moving from
+ mailsync.sh instead) is a design change for the user."""
+ with tempfile.TemporaryDirectory() as tmp:
+ env, root = setup_move(tmp)
+ write_rules(env, [SPAM_RULE])
+
+ hooks = root / ".notmuch" / "hooks"
+ hooks.mkdir(parents=True)
+ os.symlink(HOOK, hooks / "post-new")
+
+ make_message(root / "acct-one/Inbox", "junk-three",
+ "spammer@example.net", "and again")
+ result = subprocess.run(["notmuch", "new"], env=env,
+ capture_output=True, text=True)
+ assert result.returncode == 0, result.stderr
+
+ assert count(env, "tag:spam") == 3, result.stderr
+ assert count(env, "tag:new") == 0
+ assert names(root / "acct-one/Inbox/new") == ["keep-one"]
+```
+
+- [ ] **Step 2: Run it, expect FAIL on `tag:spam` (0, the hook does not move yet)**
+
+Run: `cd assets/hooks && ./test_post_new.py`
+
+The failure must be the `tag:spam` assertion. A non-zero `notmuch new` return
+code here, before any hook change, means the fixture is wrong; fix that first.
+
+- [ ] **Step 3: Write the remaining hook tests** (same place)
+
+```python
+def test_a_move_rule_puts_spam_in_each_accounts_own_spam_folder():
+ with tempfile.TemporaryDirectory() as tmp:
+ env, root = setup_move(tmp)
+ write_rules(env, [SPAM_RULE])
+
+ result = subprocess.run([str(HOOK)], env=env, capture_output=True,
+ text=True)
+ assert result.returncode == 0, result.stderr
+
+ # The files moved, each into ITS account's folder, under fresh names
+ # in cur/ carrying a flags suffix.
+ assert names(root / "acct-one/Inbox/new") == ["keep-one"]
+ assert names(root / "acct-two/Inbox/new") == []
+ one = names(root / "acct-one/Spam/cur")
+ two = names(root / "acct-two/[Provider]/Spam/cur")
+ assert len(one) == 1 and len(two) == 1, (one, two)
+ assert one[0] != "junk-one" and one[0].endswith(":2,")
+
+ # notmuch followed the rename and kept the message, not a fresh copy.
+ assert files(env, 'path:"acct-one/Spam/**"') == 1
+ assert files(env, 'path:"acct-two/[Provider]/Spam/**"') == 1
+ assert files(env, 'path:"acct-one/Inbox/**"') == 1
+
+ assert count(env, "tag:spam") == 2
+ assert count(env, "tag:spam and tag:inbox") == 0
+ # unread is the protection that reaches the server; it stays.
+ assert count(env, "tag:spam and tag:unread") == 2
+ # Account-relative, the format Restore reads.
+ assert count(env, 'tag:"moved-from:Inbox"') == 2
+ assert count(env, "tag:new") == 0
+ assert count(env, "id:keep-one@example.org and tag:inbox") == 1
+
+
+def test_a_trash_rule_skips_an_account_with_no_trash_folder():
+ with tempfile.TemporaryDirectory() as tmp:
+ env, root = setup_move(tmp)
+ write_rules(env, [dict(SPAM_RULE, move="trash")])
+
+ result = subprocess.run([str(HOOK)], env=env, capture_output=True,
+ text=True)
+ assert result.returncode == 0, result.stderr
+
+ assert len(names(root / "acct-one/Trash/cur")) == 1
+ assert count(env, "id:junk-one@example.org and tag:deleted") == 1
+ assert count(env, "id:junk-one@example.org and tag:spam") == 0
+
+ assert names(root / "acct-two/Inbox/new") == ["junk-two"]
+ assert count(env, "id:junk-two@example.org and tag:inbox") == 1
+ assert count(env, "id:junk-two@example.org and tag:deleted") == 0
+ assert "not moved" in result.stderr
+
+
+def test_the_first_move_rule_in_stage_order_wins():
+ with tempfile.TemporaryDirectory() as tmp:
+ env, root = setup_move(tmp)
+ write_rules(env, [
+ dict(SPAM_RULE, id="late", stage=50),
+ dict(SPAM_RULE, id="early", stage=10, move="trash"),
+ ])
+
+ result = subprocess.run([str(HOOK)], env=env, capture_output=True,
+ text=True)
+ assert result.returncode == 0, result.stderr
+
+ assert len(names(root / "acct-one/Trash/cur")) == 1
+ assert names(root / "acct-one/Spam/cur") == []
+ assert "claimed" in result.stderr
+
+
+def test_a_message_with_two_files_is_not_moved():
+ """Item 166's shape: one Message-ID, a file in each account. One message
+ cannot carry two origins, so it is left where it is and logged."""
+ with tempfile.TemporaryDirectory() as tmp:
+ env, root = setup_move(tmp)
+ shutil.copy(root / "acct-one/Inbox/new/junk-one",
+ root / "acct-two/Inbox/new/junk-one-copy")
+ subprocess.run(["notmuch", "new"], env=env, capture_output=True,
+ check=True)
+ write_rules(env, [SPAM_RULE])
+
+ result = subprocess.run([str(HOOK)], env=env, capture_output=True,
+ text=True)
+ assert result.returncode == 0, result.stderr
+
+ assert "junk-one" in names(root / "acct-one/Inbox/new")
+ assert "junk-one-copy" in names(root / "acct-two/Inbox/new")
+ assert count(env, "id:junk-one@example.org and tag:spam") == 0
+ assert "2 files" in result.stderr
+
+
+def test_a_file_already_in_the_spam_folder_is_tagged_not_renamed():
+ """Mail a provider filed itself, and the retry after a run whose rename
+ succeeded and whose tagging failed. Tagged, with no origin to record."""
+ with tempfile.TemporaryDirectory() as tmp:
+ env, root = setup_move(tmp)
+ make_message(root / "acct-one/Spam", "already",
+ "spammer@example.net", "filed by the provider")
+ subprocess.run(["notmuch", "new"], env=env, capture_output=True,
+ check=True)
+ write_rules(env, [SPAM_RULE])
+
+ result = subprocess.run([str(HOOK)], env=env, capture_output=True,
+ text=True)
+ assert result.returncode == 0, result.stderr
+
+ assert names(root / "acct-one/Spam/new") == ["already"]
+ assert count(env, "id:already@example.org and tag:spam") == 1
+ assert count(env, "id:already@example.org and tag:inbox") == 0
+ tags = subprocess.run(
+ ["notmuch", "search", "--output=tags", "id:already@example.org"],
+ env=env, capture_output=True, text=True, check=True).stdout
+ assert "moved-from:" not in tags, tags
+
+
+def test_a_rule_skipped_for_a_protected_removal_moves_nothing():
+ with tempfile.TemporaryDirectory() as tmp:
+ env, root = setup_move(tmp)
+ write_rules(env, [dict(SPAM_RULE, remove=["unread"])])
+
+ result = subprocess.run([str(HOOK)], env=env, capture_output=True,
+ text=True)
+ assert result.returncode == 0, result.stderr
+ assert names(root / "acct-one/Spam/cur") == []
+```
+
+- [ ] **Step 4: Run, expect every new test to FAIL**
+
+Run: `cd assets/hooks && ./test_post_new.py`
+
+`run_all()` stops at the first failure. Comment out its `fn()` loop temporarily
+only if needed to see each one; restore it before moving on.
+
+- [ ] **Step 5: Implement in `post-new`**
+
+Imports, beside `import subprocess`:
+
+```python
+import itertools
+import os
+import socket
+import time
+```
+
+After `run_tag()`:
+
+```python
+_counter = itertools.count(1)
+
+
+def fresh_name(old_name):
+ """A fresh, unique Maildir filename keeping `old_name`'s flags suffix.
+
+ Port of MaildirName::fresh() in the application, and for its reason: the
+ `,U=<n>` infix mbsync writes is meaningful only within one folder, and
+ carrying it across a folder boundary produced `Maildir error: duplicate
+ UID` on real mail (item 162). A file coming from new/ has no `:2,` yet;
+ it gets an empty one, since it is going into cur/.
+ """
+ sep = old_name.find(":2,")
+ info = old_name[sep:] if sep >= 0 else ":2,"
+ host = (socket.gethostname() or "localhost").replace("/", "_") \
+ .replace(":", "_")
+ now = time.time()
+ return (f"{int(now)}.M{int(now * 1000) % 1000}P{os.getpid()}"
+ f"Q{next(_counter)}.{host}{info}")
+
+
+def account_of(path, root, pairs):
+ """The (maildir, folder) pair whose account holds `path`, or None.
+
+ Longest maildir wins, so an account nested inside another's directory
+ resolves to itself. Compared as paths, never with startswith.
+ """
+ best = None
+ for maildir, folder in pairs:
+ if _within(path, root / maildir) and (
+ best is None or len(maildir) > len(best[0])):
+ best = (maildir, folder)
+ return best
+
+
+def origin_of(path, root, maildir):
+ """The folder `path` sits in, relative to its ACCOUNT, without cur/new.
+
+ The format MainWindow::originTagFor() writes and Restore reads:
+ `acct/Inbox/new/x` is `Inbox`.
+ """
+ parts = path.parent.relative_to(root / maildir).parts
+ if parts and parts[-1] in ("cur", "new"):
+ parts = parts[:-1]
+ return "/".join(parts)
+
+
+def apply_moves(rules):
+ """Move what each move rule matches into its account's role folder.
+
+ True when done, including when there was nothing to do. False when a
+ notmuch step failed, so the caller leaves tag:new in place. A message
+ that cannot be moved (several files, no account, no folder for the role,
+ a failed rename) is logged and left where it is; that is not a failure.
+ """
+ claimed = {}
+ for rule in rules:
+ if not rule.move:
+ continue
+ ids = search(mailrules.scoped_query(rule, SCOPE), "messages")
+ if ids is None:
+ return False
+ for message_id in ids:
+ if message_id in claimed:
+ log(f"rule '{rule.id}': {message_id} already claimed by "
+ f"rule '{claimed[message_id].id}'")
+ continue
+ claimed[message_id] = rule
+
+ if not claimed:
+ return True
+
+ root = mail_root()
+ if root is None:
+ log("no mail root; moving nothing")
+ return False
+
+ pairs = {role: qtmaildirconf.role_folders(role)
+ for role in qtmaildirconf.MOVE_ROLES}
+
+ to_tag = []
+ renamed = False
+ for message_id, rule in claimed.items():
+ paths = search(f"id:{_quote(message_id)}", "files")
+ if paths is None:
+ return False
+ if len(paths) != 1:
+ log(f"rule '{rule.id}': {message_id} has {len(paths)} files; "
+ f"not moved")
+ continue
+
+ source = Path(paths[0])
+ account = account_of(source, root, pairs[rule.move])
+ if account is None:
+ log(f"rule '{rule.id}': {message_id} is in no account with a "
+ f"{rule.move} folder; not moved")
+ continue
+
+ maildir, folder = account
+ target = root / maildir / folder
+ if _within(source, target):
+ to_tag.append((message_id, rule.move, ""))
+ continue
+
+ # The configured folder must already exist. Creating it is how a
+ # mistyped name reaches the server (item 103); cur/ inside a real
+ # folder is safe to create.
+ if not target.is_dir():
+ log(f"rule '{rule.id}': {target} does not exist; not moved")
+ continue
+
+ origin = origin_of(source, root, maildir)
+ try:
+ (target / "cur").mkdir(exist_ok=True)
+ os.rename(source, target / "cur" / fresh_name(source.name))
+ except OSError as exc:
+ log(f"rule '{rule.id}': cannot move {message_id}: {exc}")
+ continue
+ renamed = True
+ to_tag.append((message_id, rule.move, origin))
+
+ if renamed:
+ # Records each rename against the message id it already has, so the
+ # tags survive and no new.tags apply. --no-hooks, or this hook would
+ # run itself.
+ #
+ # ponytail: this also indexes any file that landed after the outer
+ # `notmuch new`, and the closing `-new` then consumes its marker
+ # unseen by the rules. Under mailsync.sh mbsync has finished and the
+ # lock is held, so nothing lands. If the hook ever runs beside a live
+ # mbsync, scope the closing `-new` to the ids seen before this call.
+ result = subprocess.run(["notmuch", "new", "--no-hooks", "--quiet"],
+ capture_output=True, text=True)
+ if result.returncode != 0:
+ log(f"notmuch new after moving failed: {result.stderr.strip()}")
+ return False
+
+ for message_id, role, origin in to_tag:
+ # What Mark spam and Delete add, minus `unread`: the hook still never
+ # removes that unattended (PROTECTED_REMOVALS).
+ arguments = ["+spam" if role == "spam" else "+deleted", "-inbox"]
+ if origin:
+ arguments.append(f"+moved-from:{origin}")
+ if not run_tag(arguments, f"id:{_quote(message_id)}"):
+ return False
+
+ log(f"moved {sum(1 for _, _, o in to_tag if o)} message(s), "
+ f"tagged {len(to_tag)}")
+ return True
+```
+
+In `main()`, the rules loop: collect the rules that ran, and skip the
+`notmuch tag` call for a move-only rule (no tag operations to pass):
+
+```python
+ applied = []
+ for rule in mailrules.ordered(store.rules):
+ refused = protected_removals(rule)
+ if refused:
+ log(f"rule '{rule.id}' would remove {', '.join(refused)}; "
+ f"skipped, this hook does not remove those unattended")
+ continue
+
+ arguments = mailrules.tag_arguments(rule)
+ query = mailrules.scoped_query(rule, SCOPE)
+ if arguments and not run_tag(arguments, query):
+ log(f"rule '{rule.id}' failed; leaving tag:new in place")
+ return 1
+ applied.append(rule)
+
+ # After every tag stage, so a later rule still sees mail in its arrival
+ # folder; before the marker goes, because the marker scopes the moves.
+ if not apply_moves(applied):
+ log("moving failed; leaving tag:new in place")
+ return 1
+```
+
+Keep the existing comment block inside the loop. Change the closing log line
+to `log(f"applied {len(applied)} rule(s)")`.
+
+- [ ] **Step 6: Run, expect all pass**
+
+Run: `cd assets/hooks && ./test_post_new.py && ./test_mailrules.py && ./test_qtmaildirconf.py`
+
+If `test_the_hook_can_move_when_notmuch_new_itself_runs_it` fails on the
+`notmuch new` return code with a lock error, STOP and report to the user. The
+fallback is a design change.
+
+---
+
+### Task 4: `TagRule::move` in C++
+
+**Files:**
+- Modify: `src/tagrules.h:32-48`, `src/tagrules.cpp` (`isKnownKey`, `validate`, `load`, `save`)
+- Test: `tests/test_tagrules.cpp`
+
+- [ ] **Step 1: Write the failing tests.** Declare in the class's private slots after `unknownFieldsSurviveASave();`:
+
+```cpp
+ void aMoveRoleRoundTripsAndAMoveOnlyRuleIsValid();
+ void anUnknownMoveRoleIsRefused();
+```
+
+Define after `TestTagRules::unknownFieldsSurviveASave()`:
+
+```cpp
+void TestTagRules::aMoveRoleRoundTripsAndAMoveOnlyRuleIsValid()
+{
+ const QString path = writeRules(R"({
+ "version": 1,
+ "rules": [
+ {"id": "junk", "query": "from:spammer@example.net", "move": "spam"},
+ {"id": "plain", "query": "from:a@example.com", "add": ["x"]}
+ ]
+ })");
+
+ TagRules rules;
+ rules.load(path);
+ QVERIFY2(rules.warnings().isEmpty(),
+ qPrintable(rules.warnings().join(QStringLiteral("; "))));
+ QCOMPARE(rules.rules().size(), 2);
+ QCOMPARE(rules.rules().at(0).move, QStringLiteral("spam"));
+ QVERIFY(!rules.rules().at(0).unknown.contains(QStringLiteral("move")));
+ QVERIFY(TagRules::validate(rules.rules()).isEmpty());
+
+ QVERIFY(rules.save(path));
+ QFile file(path);
+ QVERIFY(file.open(QIODevice::ReadOnly));
+ const QJsonArray saved = QJsonDocument::fromJson(file.readAll())
+ .object().value(QStringLiteral("rules"))
+ .toArray();
+ QCOMPARE(saved.at(0).toObject().value(QStringLiteral("move")).toString(),
+ QStringLiteral("spam"));
+ // Absent stays absent: an empty `move` on every rule would rewrite every
+ // file the dialog opens, a diff the hook's reader never asked for.
+ QVERIFY(!saved.at(1).toObject().contains(QStringLiteral("move")));
+}
+
+void TestTagRules::anUnknownMoveRoleIsRefused()
+{
+ TagRule rule;
+ rule.id = QStringLiteral("odd");
+ rule.query = QStringLiteral("from:a@example.com");
+ rule.move = QStringLiteral("Archive");
+ QCOMPARE(TagRules::validate({ rule }).size(), 1);
+
+ // Loaded, the move is dropped with a warning and the tags survive, as
+ // mailrules.py does: neither reader guesses a destination.
+ const QString path = writeRules(R"({
+ "version": 1,
+ "rules": [{"id": "odd", "query": "from:a@example.com",
+ "add": ["x"], "move": "Archive"}]
+ })");
+ TagRules rules;
+ rules.load(path);
+ QCOMPARE(rules.rules().size(), 1);
+ QVERIFY(rules.rules().at(0).move.isEmpty());
+ QCOMPARE(rules.warnings().size(), 1);
+}
+```
+
+- [ ] **Step 2: Build, expect a COMPILE failure** (`TagRule` has no `move`)
+
+Run: `cmake --build build`
+
+- [ ] **Step 3: Implement**
+
+`src/tagrules.h`, in `TagRule` after `remove`:
+
+```cpp
+ /// "spam" or "trash", or empty. An account ROLE, never a folder name: the
+ /// hook resolves it per message to that account's configured folder, so
+ /// a typo cannot create a folder on the server (item 103, item 214).
+ QString move;
+```
+
+`src/tagrules.cpp`, `isKnownKey`: add `QStringLiteral("move"),` to the list.
+In the anonymous namespace, after `stringsOf`:
+
+```cpp
+/// What `move` may say. mailrules.py and qtmaildirconf.py carry the same two.
+bool isMoveRole(const QString &role)
+{
+ return role == QStringLiteral("spam") || role == QStringLiteral("trash");
+}
+```
+
+`validate()`, replacing the add/remove check:
+
+```cpp
+ if (!rule.move.isEmpty() && !isMoveRole(rule.move)) {
+ problems.append(QObject::tr("'%1': move '%2' is not spam or trash")
+ .arg(where, rule.move));
+ }
+ if (rule.add.isEmpty() && rule.remove.isEmpty() && rule.move.isEmpty())
+ problems.append(QObject::tr("'%1': adds, removes and moves nothing")
+ .arg(where));
+```
+
+`load()`, replacing the add/remove block:
+
+```cpp
+ rule.add = stringsOf(object.value(QStringLiteral("add")));
+ rule.remove = stringsOf(object.value(QStringLiteral("remove")));
+ rule.move = object.value(QStringLiteral("move")).toString();
+ if (!rule.move.isEmpty() && !isMoveRole(rule.move)) {
+ m_warnings.append(QObject::tr("Rule '%1': move '%2' is not spam "
+ "or trash; ignored")
+ .arg(rule.id, rule.move));
+ rule.move.clear();
+ }
+ if (rule.add.isEmpty() && rule.remove.isEmpty() && rule.move.isEmpty()) {
+ m_warnings.append(QObject::tr("Rule '%1': adds, removes and moves "
+ "nothing; dropped").arg(rule.id));
+ continue;
+ }
+```
+
+`save()`, after inserting `remove`:
+
+```cpp
+ // Only when set: a file with no moves stays byte-identical on save.
+ if (!rule.move.isEmpty())
+ object.insert(QStringLiteral("move"), rule.move);
+```
+
+- [ ] **Step 4: Build and run, expect all pass**
+
+Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_tagrules`
+
+---
+
+### Task 5: the dialog's *Move to* combo
+
+**Files:**
+- Modify: `src/tagrulesdialog.h` (member, two test hooks), `src/tagrulesdialog.cpp` (form at :161-175, connects at :349-360, load at :646, apply at :702)
+- Test: `tests/test_tagrules.cpp`
+
+- [ ] **Step 1: Write the failing test.** Declare `void theDialogWritesTheChosenMoveRole();` and define after `aRuleAddedAndNamedInTheDialogSurvivesAReopen()`:
+
+```cpp
+void TestTagRules::theDialogWritesTheChosenMoveRole()
+{
+ QTemporaryDir configHome;
+ QVERIFY(configHome.isValid());
+ qputenv("XDG_CONFIG_HOME", configHome.path().toUtf8());
+ QVERIFY(QDir().mkpath(configHome.filePath(QStringLiteral("mailrules"))));
+
+ const QString stored = configHome.filePath(
+ QStringLiteral("mailrules/rules.json"));
+ QFile out(stored);
+ QVERIFY(out.open(QIODevice::WriteOnly));
+ out.write(R"({
+ "version": 1,
+ "rules": [
+ {"id": "vendor", "query": "from:vendor.example.org",
+ "add": ["vendor"], "stage": 50, "enabled": true}
+ ]
+ })");
+ out.close();
+
+ {
+ TagRulesDialog dialog;
+ dialog.selectRuleForTest(0);
+ QCOMPARE(dialog.moveForTest(), QString());
+ dialog.setMoveForTest(QStringLiteral("spam"));
+ dialog.saveForTest();
+ QVERIFY(dialog.warningTextForTest().isEmpty());
+ }
+
+ TagRules reloaded;
+ reloaded.load(stored);
+ QCOMPARE(reloaded.rules().at(0).move, QStringLiteral("spam"));
+
+ // And back the other way: the stored role shows on reopen, so the next
+ // save cannot silently clear it.
+ TagRulesDialog reopened;
+ reopened.selectRuleForTest(0);
+ QCOMPARE(reopened.moveForTest(), QStringLiteral("spam"));
+}
+```
+
+- [ ] **Step 2: Build, expect a COMPILE failure** (no `moveForTest`)
+
+- [ ] **Step 3: Implement**
+
+`src/tagrulesdialog.h`, beside `void setTagsForTest(const QString &tags);`:
+
+```cpp
+ void setMoveForTest(const QString &role);
+ QString moveForTest() const;
+```
+
+and the member after `QLineEdit *m_remove = nullptr;`:
+
+```cpp
+ QComboBox *m_move = nullptr;
+```
+
+`src/tagrulesdialog.cpp`, after `m_remove` is created:
+
+```cpp
+ // The stored value is the item DATA, the wire-format role. The label is
+ // translated, and nothing may match on it ("Translating a string that
+ // something MATCHES on" in AGENTS.md).
+ m_move = new QComboBox(this);
+ m_move->addItem(tr("Don't move"), QString());
+ m_move->addItem(tr("Spam folder"), QStringLiteral("spam"));
+ m_move->addItem(tr("Trash folder"), QStringLiteral("trash"));
+ m_move->setToolTip(tr("Moves matching new mail into the spam or trash "
+ "folder of the account it arrived in, and takes it "
+ "out of the inbox. It stays unread."));
+```
+
+after `form->addRow(tr("Remove tags"), m_remove);`:
+
+```cpp
+ form->addRow(tr("Move to"), m_move);
+```
+
+with the other connects:
+
+```cpp
+ connect(m_move, &QComboBox::currentIndexChanged,
+ this, &TagRulesDialog::applyEditsToCurrentRule);
+```
+
+in the rule load, after `m_remove->setText(...)`:
+
+```cpp
+ m_move->setCurrentIndex(qMax(0, m_move->findData(rule.move)));
+```
+
+in `applyEditsToCurrentRule`, after `rule.remove = ...`:
+
+```cpp
+ rule.move = m_move->currentData().toString();
+```
+
+and the hooks, beside `setTagsForTest`:
+
+```cpp
+void TagRulesDialog::setMoveForTest(const QString &role)
+{
+ m_move->setCurrentIndex(m_move->findData(role));
+}
+
+QString TagRulesDialog::moveForTest() const
+{
+ return m_move->currentData().toString();
+}
+```
+
+- [ ] **Step 4: Build and run, expect all pass**
+
+Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_tagrules`
+
+---
+
+### Task 6: translations, changelog, backlog, 212's note
+
+**Files:**
+- Modify: `translations/qtmaildir_it_IT.ts`, `CHANGELOG.md`, `docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md`, `docs/superpowers/specs/2026-10-31-rule-apply-and-archive-design.md`
+
+- [ ] **Step 1: Refresh the catalogue**
+
+Run: `lupdate-qt6 src/ -ts translations/qtmaildir_it_IT.ts -no-obsolete -locations none`
+Expected: zero context warnings, new entries marked `type="unfinished"`.
+
+- [ ] **Step 2: Translate each new entry** (remove `type="unfinished"`):
+
+| source | translation |
+|---|---|
+| `Don't move` | `Non spostare` |
+| `Spam folder` | `Cartella spam` |
+| `Trash folder` | `Cestino` |
+| `Move to` | `Sposta in` |
+| the tooltip | `Sposta la posta nuova corrispondente nella cartella spam o nel cestino dell'account in cui è arrivata, e la toglie dalla posta in arrivo. Resta da leggere.` |
+| `'%1': move '%2' is not spam or trash` | `'%1': lo spostamento '%2' non è spam né cestino` |
+| `Rule '%1': move '%2' is not spam or trash; ignored` | `Regola '%1': lo spostamento '%2' non è spam né cestino; ignorato` |
+| `'%1': adds, removes and moves nothing` | `'%1': non aggiunge, non rimuove e non sposta nulla` |
+| `Rule '%1': adds, removes and moves nothing; dropped` | `Regola '%1': non aggiunge, non rimuove e non sposta nulla; scartata` |
+
+In the `.ts` file apostrophes are `&apos;`; match the file's existing escaping.
+
+- [ ] **Step 3: Full suite**
+
+Run: `cmake --build build && ctest --test-dir build --output-on-failure`
+Expected: all pass, including `translations` and the three `hooks_*` tests.
+
+- [ ] **Step 4: Changelog.** Under `## [Unreleased]` → `### Added`:
+
+```markdown
+- A tagging rule can move the mail it matches into the spam or trash
+ folder, through a new **Move to** field in the rules dialog. Each message
+ goes to the folder its own account configures (`spam` / `trash`), never to
+ a folder named in the rule, and leaves the inbox while staying unread. It
+ applies to mail as it arrives; Restore and Not spam work on it as on a
+ message moved by hand.
+```
+
+- [ ] **Step 5: Item 212's spec.** Append to the end of `docs/superpowers/specs/2026-10-31-rule-apply-and-archive-design.md`:
+
+```markdown
+## Addendum, 2026-11-16: rules that move (item 214)
+
+A rule may now carry `"move": "spam" | "trash"`. When Apply is built it must
+honour that field by sending the matched ids through
+`NotmuchWorker::moveMessages()` with the same tags Mark spam / Delete use
+(minus `unread`, matching the hook), so the move lands on the undo stack.
+The count in the confirmation names the move as well as the tag change.
+```
+
+- [ ] **Step 6: Backlog row 214** in `docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md`: status cell becomes `built 2026-MM-DD on \`rule-move\`, awaiting the user's hand test`, keeping the rest of the cell.
+
+---
+
+### Task 7: hand-over (stop here)
+
+- [ ] **Step 1:** Report to the user, without committing:
+ - suite result (counts from `ctest`)
+ - the hand round trip they need to run, from AGENTS.md "Changing the rule format": in the worktree build, open the rules dialog (`./build/src/qtmaildir` is theirs to launch), set a rule's *Move to* to Spam folder, save; confirm `~/.config/mailrules/rules.json` carries `"move": "spam"` on that rule and that every other rule is byte-identical (`git diff --no-index` against a copy taken first); then run `assets/hooks/test_post_new.py` once more.
+ - that the LIVE hook is untouched until the merge, because the live `hook_dir` points at the main checkout.
+- [ ] **Step 2:** On the user's go-ahead: commit in the worktree (GPG-signed, one commit per concern: hook + Python readers; C++ reader + dialog; translations + docs), merge `rule-move` into `master`, delete the local branch only, remove the worktree, push.
diff --git a/docs/superpowers/specs/2026-11-16-rule-move-design.md b/docs/superpowers/specs/2026-11-16-rule-move-design.md
index 3c2999a..95bac9c 100644
--- a/docs/superpowers/specs/2026-11-16-rule-move-design.md
+++ b/docs/superpowers/specs/2026-11-16-rule-move-design.md
@@ -57,20 +57,34 @@ 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 (<query>)`. 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
+2. For each claimed message, resolve its file to an account by path (the
+ account whose `maildir` contains it, compared as paths) 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.
+3. Skip, with a log line: a message with MORE THAN ONE file (mail sent to
+ another of the user's own accounts, item 166: two files, two accounts, and
+ one message cannot carry two origins); a file in no configured account; an
+ account with no folder for the role (`Config` already warns about that,
+ since both keys are mandatory); a file already in the destination folder.
+ Never invent a folder.
4. Rename the file into `<mail_root>/<account maildir>/<folder>/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.
+ FRESH name (no `,U=` infix, item 162; ported from `MaildirName::fresh()`,
+ keeping the `:2,` flags suffix and adding an empty `:2,` when the file
+ came from `new/` with none). `cur/`, never `new/`. Record the origin before
+ the rename.
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:<origin>` (one per origin folder,
- same tag format the app writes and Restore reads), `+spam` for the spam
- role, and `-inbox`. Do not touch `unread`.
+ rename against the existing message id, keeping its tags. A renamed file
+ with a known id is not a new message and gets no `new.tags`.
+6. Then tag each relocated id: `+moved-from:<origin>`, where origin is the
+ folder relative to the ACCOUNT's maildir (`MainWindow::originTagFor()`'s
+ format, which Restore reads), `+spam` for the spam role or `+deleted` for
+ the trash role (what Mark spam and Delete add), and `-inbox`. Do not touch
+ `unread`. No existing `moved-from:` needs stripping: the message only just
+ arrived.
+
+The inner `notmuch new` also indexes any file that landed after the outer one,
+and the closing `-new` would then consume that file's marker without rules
+having seen it. Under `mailsync.sh` mbsync has finished and the lock is held,
+so nothing lands; the window is accepted and commented in the code.
### Failure
@@ -79,22 +93,27 @@ After all tag stages have run, and BEFORE `tag:new` is consumed:
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)
+A file already inside the destination folder is not renamed but IS tagged
+(without an origin): that covers mail a provider filed there itself, and a
+previous run whose rename succeeded and whose tagging failed.
+
+### To verify first (the hook task's first test)
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.
+renamed file with a known id keeps its tags and gets no `new.tags`. A test
+installs the hook in a throwaway database and runs a plain `notmuch new`. If
+it fails, the fallback is to defer moves to a step in `assets/mailsync.sh`
+after `notmuch new` returns; that is a design change and goes back to the
+user.
## 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.
+folder* (labels translated; the stored value is the wire-format role, kept as
+item data, per the "translating a string something matches on" rule). No
+per-account warning: `spam` and `trash` are mandatory keys and `Config` already
+reports a missing one.
## Unchanged
@@ -105,9 +124,11 @@ it, since the hook will skip that account's mail.
## 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.
+ tags survive, `moved-from:` written account-relative, `-inbox`, `unread`
+ kept, `+spam` / `+deleted` by role, missing role skipped, two rules claiming
+ one message, a multi-file message skipped, a file already in place left
+ alone. Plus one test that installs the hook in the throwaway database's
+ hook directory and runs a plain `notmuch new`, which is the nesting check.
- `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.