aboutsummaryrefslogtreecommitdiffstats
path: root/docs/superpowers/plans/2026-11-16-rule-move.md
blob: 4e43280959b9c1296b4fd0dd3b3dfb9f08071228 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
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.