# 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 `//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=` 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 `'`; 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.