aboutsummaryrefslogtreecommitdiff
path: root/docs/design/2026-07-17-todo-cleanup-dated-seal-proposal.md
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-07-18 19:55:43 -0500
committerCraig Jennings <c@cjennings.net>2026-07-18 19:55:43 -0500
commitbc1d81d835237343a4ced82a9025f2dc34f45865 (patch)
tree173150aadac7932eb55759bf294fb18ca2b453a7 /docs/design/2026-07-17-todo-cleanup-dated-seal-proposal.md
parent6523ed5b789689a2b77925fb3825570b2d8e5686 (diff)
downloadrulesets-bc1d81d835237343a4ced82a9025f2dc34f45865.tar.gz
rulesets-bc1d81d835237343a4ced82a9025f2dc34f45865.zip
chore(todo): file four backlog tasks from the inbox pass
Filed as [#B] work items with their origin proposals preserved under docs/design/: the todo-cleanup dated-seal archiving model, the dated-log planning-line strip plus its lint backstop, a hook to enforce the task-boundary inbox check, and home's colloquialisms / "the list" before-close-queue convention. The first two both touch todo-cleanup.el and are cross-linked to build as one batch. The last two carry the design worked out this session so they start warm.
Diffstat (limited to 'docs/design/2026-07-17-todo-cleanup-dated-seal-proposal.md')
-rw-r--r--docs/design/2026-07-17-todo-cleanup-dated-seal-proposal.md38
1 files changed, 38 insertions, 0 deletions
diff --git a/docs/design/2026-07-17-todo-cleanup-dated-seal-proposal.md b/docs/design/2026-07-17-todo-cleanup-dated-seal-proposal.md
new file mode 100644
index 0000000..61d457c
--- /dev/null
+++ b/docs/design/2026-07-17-todo-cleanup-dated-seal-proposal.md
@@ -0,0 +1,38 @@
+Proposal: change todo-cleanup.el's --archive-done aging to a dated-seal model
+
+Origin: work project, 2026-07-17. Reconciling a stale rotation convention with the tool's actual behavior. Craig ratified the design in-session.
+
+## The problem
+
+`--archive-done` today does two things: move level-2 DONE/CANCELLED out of Open Work into Resolved, then age Resolved by moving subtrees older than `tc-archive-retain-days` (default 7) into one rolling file `tc-archive-file` (default archive/task-archive.org).
+
+Two mismatches with the intended convention:
+
+1. Retention is 7 days; the convention wants the last month kept inline in Resolved.
+2. One rolling file forever; the convention wants periodic dated files so todo.org's archive is browsable by seal date.
+
+An earlier attempt to name files by calendar quarter (resolved-YYYY-QN.org) hit a seam: with a one-month retention window, a task closed in the last month of a quarter isn't archived until after the quarter boundary, so a quarter-named file can't hold it without mislabeling.
+
+## The design (ratified)
+
+Redefine the sealed file by a predicate that's always true of its contents, and date it by the seal run rather than by calendar quarter:
+
+- A level-2 DONE/CANCELLED subtree is archived when its CLOSED date is older than one month, OR its CLOSED date can't be parsed (archive regardless — a keyword-complete task with no readable close date is cruft, not live work).
+- The working (open) file keeps the existing name task-archive.org. A seal renames it to resolved-YYYY-MM-DD.org (the seal date) and starts a fresh working file.
+- The dated file means "everything sealed as of that date," not a quarter — so a late-quarter close archived after a boundary is never mislabeled. Cadence (quarterly) becomes independent of correctness; slip is harmless.
+
+## Concrete changes to todo-cleanup.el
+
+1. `tc-archive-retain-days` default 7 → 31 (or expose it; the value should reflect "one month"). Reconcile the test at test-todo-cleanup.el:362 that asserts 7-day aging.
+2. Aging predicate: archive when `closed < now - retain-days` OR `closed` is unparseable. Today an unparseable-CLOSED subtree is already moved out in aging per the docstring ("those with no parseable CLOSED date are moved out") — keep that, and make it explicit in the contract.
+3. Add a seal step (new flag, e.g. `--seal`, or fold into a boundary check): when invoked, rename the current `tc-archive-file` (task-archive.org) → `resolved-<today>.org` beside it and let the next aging recreate a fresh working file. Whether the seal fires automatically at a quarter boundary or stays a manual flag is your call — the manual quarterly rotation task covers it until then.
+4. Tests: update the file-aging tests (test-todo-cleanup.el:362, :378, :491, :513, :518) for the new retain default and the seal/rename behavior. The gitignore-inheritance logic (tc--ensure-archive-gitignored) applies unchanged to both the working and sealed names.
+
+## Companion state already applied in the work project (for reference, not to sync)
+
+- todo.org grew a `* Work Resolved` section; 30 level-2 DONE/CANCELLED moved there.
+- archive/task-archive.org renamed to archive/resolved-2026-07-17.org (grandfathered H1 seal), inbound link updated.
+- archive/README.org rewritten to the dated-seal contract above.
+- The rotation task rewritten to the new procedure.
+
+The rulesets change is only the todo-cleanup.el behavior + its tests. The README lives per-project (this one is already updated); if rulesets ships a canonical archive README template, align it to the dated-seal contract too.