docs: design applying a rule to existing mail

Two items found together. A rule edit reaches only new mail, and a rule
that removes inbox is skipped whole by the post-new hook, which is why the
promo rule has never tagged an arrival. The spec adds an Apply button
that saves, counts what would change and confirms with that count, and an
optional per-rule allow_archive the hook honours for inbox only.

Items 212 and 213.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 35 insertions, 0 deletions

diff --git a/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md b/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md
index a3df5be..6e36905 100644
--- a/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md
+++ b/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md
@@ -149,6 +149,8 @@ taking that too literally.
 | 209 | The calendar has no Week view | presentation | M | open, from 206's brainstorm. The occurrence list is the seam: a new painter over CalendarItem, no store change |
 | 210 | A repeating event cannot be edited "this and following" | workflow | S-M | open, from 206's brainstorm. Splits a series into two files, divides EXDATEs and overrides, shifts moved RECURRENCE-IDs, converts COUNT; see the spec's Out of scope |
 | 211 | Archiving thousands of selected rows freezes the window | defect | S | **done** 2026-10-31, unreleased. Cubic optimistic-update path made linear: a lazily rebuilt id index in `ThreadListModel` and `MainWindow::batchModelWrites()` refreshing the action labels once per loop. A write now reads "applying…" until the worker has run it, then "done". Hand-tested on a 10158-message archive |
+| 212 | A rule edit reaches only new mail; applying it to the backlog is a hand-typed `notmuch tag` | workflow | M | open, designed: `specs/2026-10-31-rule-apply-and-archive-design.md` Part A. Apply saves, counts what would change, confirms with the count (a new documented exception to the no-confirmation rule), writes through `applyTags` for exact undo |
+| 213 | A rule removing `inbox` is skipped whole by the hook, so promo mail arrives untagged | defect | S-M | open, designed: same spec, Part B. Optional per-rule `allow_archive`, both readers, no version bump; `unread` stays refused; the dialog warns about rules the hook will skip |
 | 73 | This backlog is past four thousand lines | maintenance | S | **done** 2026-08-13; 5056 lines to 578, closed sections moved to `2026-08-03-post-0.1.0-usability-closed.md` |
 | 74 | "Searching..." keeps claiming a query is running while rows are already arriving | feedback | XS | **done** 2026-08-15, unreleased. The status-bar half only: the bar now counts threads per batch. The cold-cache delay itself was measured in 2026-08-11 and is not fixable here |
 | 75 | The tagging rules window forgets its size and its column widths | persistence | S | **done** 2026-08-13, shipped in 0.17.0. The window-kind question is left open, see the closed-items file |
@@ -1698,3 +1700,36 @@ The split runs through `CalendarWriter`, so it inherits the stale check: a
 server-normalised source must refuse rather than divide a file it does not
 recognise. See the spec's Out of scope for the full list of what the split has
 to divide.
+
+## 212. A rule edit reaches only new mail
+
+**Observed.** From the user, 2026-10-31: after adding an address to the promo
+rule, "I have to manually go and apply the tags, because filters run on new
+mail only."
+
+**Cause.** Not a defect. The `post-new` hook scopes every rule to `tag:new`,
+and backfill was deliberately deferred by the tagging-rules spec until the
+confirmation question was settled.
+
+**Approach.** See `specs/2026-10-31-rule-apply-and-archive-design.md`, Part A.
+
+**Constraints.** Revises the no-confirmation rule in `CLAUDE.md` with a second
+exception, by property: a write scoped to the whole mailbox confirms with the
+count. Undo still applies.
+
+## 213. A rule removing `inbox` is skipped whole by the hook
+
+**Observed.** Found while designing 212. Every sync logs
+`rule 'promo' would remove inbox; skipped`, so new promotional mail is never
+tagged `promo` and stays in the inbox. This is how the 10k messages of item
+211 accumulated.
+
+**Cause.** Verified in `assets/hooks/post-new`: `PROTECTED_REMOVALS` is
+`{unread, inbox}` and a rule naming either is `continue`d past entirely, not
+applied without the removal. The rules dialog says nothing about it.
+
+**Approach.** See the same spec, Part B.
+
+**Constraints.** A rule-format change: both readers, both suites, and the hand
+round trip under "Changing the rule format". The hook runs every ten minutes
+on real mail.