Merge pull request #8 from tteschon/replace-cadence-with-rrule-frequency

Replace cadence with an RRULE-valued frequency field

Author: tteschon

plugins/work-skills/skills/obsidian-task-grooming/SKILL.md

@@ -39,7 +39,7 @@ obsidian base:query path="<base path>" format=json
 ```
 
 **Test the values this returns, never the note text.** The task template writes
-`cadence:` as an empty key on every note, so a check for a missing line matches
+`frequency:` as an empty key on every note, so a check for a missing line matches
 nothing and reports a clean base no matter how much has drifted. `base:query`
 returns `null` for an empty key and a genuinely absent one alike, which is the
 only place the two look the same.
@@ -48,7 +48,7 @@ Below, "empty" means the queried value is `null` or `""`.
 
 ## Step 2 - Check A, unscheduled one-time tasks
 
-**Rule** - `status` is not `done`, `due` is empty, and `cadence` is empty.
+**Rule** - `status` is not `done`, `due` is empty, and `frequency` is empty.
 
 These are invisible to the schedule, not merely unprioritised. The base's
 `Today` and `This week` views both filter on `due != null`, so a task with no
@@ -68,7 +68,7 @@ A **recurring** task with an empty `due` is a different thing and not a defect
 
 ## Step 3 - Check B, stale active status
 
-**Rule** - `status` is `active`, `cadence` is set, `due` is in the future, and
+**Rule** - `status` is `active`, `frequency` is set, `due` is in the future, and
 `last done` is not empty.
 
 A correct roll-forward ends at `status: backlog`; that is the last property
@@ -77,11 +77,11 @@ documented lifecycle. It means the roll-forward ran and recomputed `due`, and
 only the status reset failed to stick.
 
 Confirm the arithmetic before calling it stale. A task whose `due` sits exactly
-one cadence interval past its `last done` was rolled forward, and the status is
+one interval past its `last done` was rolled forward, and the status is
 the only thing wrong with it:
 
 ```
-Crosstrek Oil Change    cadence: every 6 months
+Crosstrek Oil Change    frequency: FREQ=MONTHLY;INTERVAL=6;BYMONTHDAY=-1
   last done 2026-06-19    due 2026-12-19    <- exactly 6 months on, rolled forward
 ```
 
@@ -105,15 +105,15 @@ reason they can be found and cleared at all.
 
 | Row | Meaning | Do |
 |---|---|---|
-| `done`, `cadence` empty | A finished one-time task | Sweep it - delete after confirmation |
-| `done`, `cadence` set | A recurring task that has silently stopped recurring | **Never delete.** Report for `obsidian-tasks` Step 4 roll-forward |
+| `done`, `frequency` empty | A finished one-time task | Sweep it - delete after confirmation |
+| `done`, `frequency` set | A recurring task that has silently stopped recurring | **Never delete.** Report for `obsidian-tasks` Step 4 roll-forward |
 
-**`cadence` is what keeps a task out of the sweep.** A done row carrying a
-cadence is a recurring chore that was marked finished and never rolled
+**`frequency` is what keeps a task out of the sweep.** A done row carrying a
+rule is a recurring chore that was marked finished and never rolled
 forward; deleting it destroys the schedule instead of repairing it. This guard
 lives here and only here - never re-implement it elsewhere. It is also the
 finding worth naming out loud, because nothing else in the vault will ever
-flag it: the row sits in the base looking finished, its cadence intact, and it
+flag it: the row sits in the base looking finished, its rule intact, and it
 will simply never come due again.
 
 When `base:views` lists a `Sweep` view, `base:query ... view="Sweep"` returns
@@ -158,8 +158,8 @@ is a result, and silence reads as an unrun check.
 
 ## Gotchas
 
-- **`cadence` is empty on a one-time task, not missing.** The template writes
-  the key on every note, so `cadence:` appears everywhere and a test for an
+- **`frequency` is empty on a one-time task, not missing.** The template
+  writes the key on every note, so `frequency:` appears everywhere and a test for an
   absent line matches nothing - a grooming run built that way finds zero
   problems and reports success. Test the value from `base:query`.
 - **Never pass `type=` to `property:set`.** It rewrites the property's type
@@ -172,7 +172,11 @@ is a result, and silence reads as an unrun check.
 - **`obsidian delete` trashes by default; never pass `permanent`.** Plain
   `delete` prints `Moved to trash: <path>` and the note stays recoverable from
   the vault trash, which is what makes the sweep safe to confirm in a batch.
-- **Sweep only on the queried `cadence`, never on the note text.** A recurring
+- **An empty `frequency` and `frequency: ""` are different to Bases.** A bare
+  key is `null`; an empty string is not, so a `frequency != null` filter
+  matches one-time tasks and a view built on it returns wrong rows silently.
+  If a sweep candidate list looks too short, check for `""` in the notes.
+- **Sweep only on the queried `frequency`, never on the note text.** A recurring
   task read the wrong way looks one-time, and the sweep deletes the schedule.
   This is the one place in the skill where a bad read destroys work.
 - **Never read task state from the Kanban board.** It does not write back to

plugins/work-skills/skills/obsidian-tasks/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: obsidian-tasks
-description: Creates and manages task notes in an Obsidian vault - one note per task, identified by a type property set to task and collected by a Bases file, carrying status, due, priority, category, and cadence. Use this skill when the user wants to add a task, mark one done, change its priority or due date, roll a recurring chore forward after doing it, or ask what to work on next - what are my top tasks, what is overdue, what should I do this weekend, add mowing the lawn to my tasks, I just changed the oil. Also use it when the user mentions their task base, a task repo, a task note's status or cadence, or a backlog of home, yard, or vehicle chores. Do not use it for checkbox tasks inline in note bodies - what the obsidian tasks command lists - do not use it to review the whole base or to sweep out finished tasks - groom my tasks, what is stale, clear out my done tasks - which is obsidian-task-grooming; and do not use it for general vault reading, searching, or note editing - obsidian-vault covers those.
+description: Creates and manages task notes in an Obsidian vault - one note per task, identified by a type property set to task and collected by a Bases file, carrying status, due, priority, category, and an RRULE frequency. Use this skill when the user wants to add a task, mark one done, change its priority or due date, roll a recurring chore forward after doing it, or ask what to work on next - what are my top tasks, what is overdue, what should I do this weekend, add mowing the lawn to my tasks, I just changed the oil. Also use it when the user mentions their task base, a task repo, a task note's status or frequency, or a backlog of home, yard, or vehicle chores. Do not use it for checkbox tasks inline in note bodies - what the obsidian tasks command lists - do not use it to review the whole base or to sweep out finished tasks - groom my tasks, what is stale - which is obsidian-task-grooming; and do not use it for general vault reading, searching, or note editing - obsidian-vault covers those.
 compatibility: Requires the obsidian CLI and a vault whose task notes carry a type property of task, collected by a Bases file
 ---
 
@@ -23,10 +23,15 @@ exit codes cannot be trusted; do not re-derive it. Run its check, then
 
 ```bash
 command -v obsidian          # exit 1 - stop, not fixable from the shell
+command -v uv                # needed to evaluate RRULEs in Step 4
 obsidian vault info=name     # confirm the right vault
 obsidian bases               # find the task base
 ```
 
+Rolling a recurring task forward evaluates an RFC 5545 `RRULE` and so needs
+Python as well as the CLI - `uv run --with python-dateutil` supplies it per
+invocation, with no project dependency. Every other step is shell only.
+
 | Found | Do |
 |---|---|
 | A task base | Use the path `bases` printed, exactly |
@@ -87,7 +92,7 @@ confusing here, because `type` is also the property that marks a task:
 `name=type` is correct, `type=text` is the destructive one.
 
 Ask for `category` and `priority` when the user did not say; leave `due` and
-`cadence` empty rather than inventing them. If `base:create` fails, fall back
+`frequency` empty rather than inventing them. If `base:create` fails, fall back
 to `create name="<name>" path="<folder>"` then
 `property:set name=type value=task` - the note is only a task once it has
 that property.
@@ -104,9 +109,9 @@ The canonical set is `backlog`, `active`, `done`:
 obsidian property:set name=status value=active path="<path>"
 ```
 
-**Check `cadence` before writing `done`** - it separates the two kinds of
+**Check `frequency` before writing `done`** - it separates the two kinds of
 task, and the branch is not recoverable by reading the note afterwards. A
-task *with* a cadence goes to Step 4 and never gets `status: done`. A task
+task *with* a rule goes to Step 4 and never gets `status: done`. A task
 *without* one is finished for good here, and finishing it removes the note:
 
 ```bash
@@ -130,20 +135,33 @@ after. The ones already sitting in the base are swept by
 
 A recurring task is never left `done`; that is what makes it recur. Marking
 one `done` and stopping is still the most likely mistake in this skill, but it
-no longer hides: done tasks stay in the base, so a done row carrying a cadence
-is visible as the anomaly it is. `obsidian-task-grooming` lists those rows for
-roll-forward and never deletes them - **`cadence` is what keeps a task out of
-the sweep**, which is one more reason never to clear it.
+no longer hides: done tasks stay in the base, so a done row carrying a
+`frequency` is visible as the anomaly it is. `obsidian-task-grooming` lists
+those rows for roll-forward and never deletes them - **`frequency` is what
+keeps a task out of the sweep**, which is one more reason never to clear it.
 
-Due dates snap to the **end of a period**, computed from today rather than
-from `last done`. Worked from a completion on Monday 2026-08-17:
+`frequency` holds an RFC 5545 `RRULE`. The new `due` is the next occurrence
+**strictly after today**, anchored on the task's current `due`:
 
-| Cadence | New `due` |
-|---|---|
-| `weekly` | 2026-08-30 (Sunday) |
-| `monthly` | 2026-09-30 |
-| `every 6 months` | 2027-02-28 |
-| `annual` | 2027-08-31 |
+```bash
+uv run --with python-dateutil python3 -c '
+import sys, datetime as d
+from dateutil.rrule import rrulestr
+r = rrulestr(sys.argv[1], dtstart=d.datetime.fromisoformat(sys.argv[2]))
+print(r.after(d.datetime.fromisoformat(sys.argv[3])).date().isoformat())
+' "<frequency>" "<current due>" "<today>"
+```
+
+**Never compute this by hand.** RRULE's `BY*` parts expand or limit depending
+on the `FREQ` above them, and the intuitive spelling of "annually on the last
+day of the month" - `FREQ=YEARLY;BYMONTHDAY=-1` - silently yields a *monthly*
+series. `references/recurrence.md` has the value grammar, the traps, and the
+verified cases.
+
+Anchoring on `due` is what makes a late completion land on the next scheduled
+slot instead of shifting every future cycle. Confirm afterwards that the new
+`due` is itself on the rule's grid - an off-grid anchor rolls forward by days
+instead of months.
 
 Then write three properties, in this order, and append to the body:
 
@@ -159,10 +177,10 @@ part number, what was done - goes on the body log line under a
 `## Service log` heading, **never** into those two fields. The body log also
 keeps the history that `last done` overwrites.
 
-Read `references/recurrence.md` for any cadence outside that table, the
-algorithm behind it, and the month-end and leap-year edges. It exists to stop
-you rolling the completion date forward by the interval instead of snapping
-to a period end - a drift that compounds every cycle.
+Read `references/recurrence.md` before writing or editing any rule. It holds
+the `RRULE` value grammar, the evaluator invocation, the grid-alignment
+assertion, and the expand-versus-limit traps that make hand-computed dates
+wrong without erroring.
 
 ## Step 5 - Sweeping the base belongs to grooming
 
@@ -171,8 +189,8 @@ them out is `obsidian-task-grooming`'s Step 4: it surveys the whole base, lists
 every candidate by name, and deletes on a single confirmation. Hand off to it
 rather than sweeping here.
 
-The rule that decides what may go - **`cadence` empty means sweepable,
-`cadence` set means never delete, roll it forward instead** - lives there and
+The rule that decides what may go - **`frequency` empty means sweepable,
+`frequency` set means never delete, roll it forward instead** - lives there and
 nowhere else. Do not re-derive it in this skill; two copies of that guard are
 two things that can drift apart, and the failure mode is a deleted recurring
 schedule.
@@ -258,12 +276,21 @@ from the vault trash. If a command printed `Error: `, say what did not happen.
   `status: done`, so `base:query` is the full inventory rather than a list of
   open work. Drop done rows before ranking, and never schedule one as if it
   were outstanding. Clearing them out is grooming's sweep, not this skill's.
-- **`cadence` is empty on a one-time task, not missing.** The template writes
-  the key with no value, so `cadence:` appears on every task note and a test
-  for an absent line matches nothing - a branch built that way sends every
-  task down the one-time path. `base:query` returns `null` for an empty key and for a
-  genuinely absent one alike, which is why the queried value is the one to
-  test.
+- **`frequency` is empty on a one-time task, not missing.** The template
+  writes the key with no value, so `frequency:` appears on every task note and
+  a test for an absent line matches nothing - a branch built that way sends
+  every task down the one-time path. `base:query` returns `null` for an empty
+  key and for a genuinely absent one alike, which is why the queried value is
+  the one to test.
+- **Never seed an empty `frequency` with `property:set value=""`.** That
+  writes `frequency: ""`, and an empty string is **not** `null` to Bases, so
+  every `frequency != null` filter starts matching one-time tasks and the view
+  returns wrong rows with no error. The template's bare `frequency:` key is
+  null; let the template write it.
+- **A new property is invisible to `base:query` until the base names it.**
+  Results are keyed by the view's columns, so a property written to every note
+  reads back as absent until it is added to the `.base` file. Verify a new
+  field against `obsidian read`, or update the base first.
 - **`obsidian delete` trashes by default; never pass `permanent`.** Plain
   `delete` prints `Moved to trash: <path>` and the note stays recoverable from
   the vault trash until the user empties it. `permanent` skips that, and

plugins/work-skills/skills/obsidian-tasks/references/base.md

@@ -21,7 +21,7 @@ formulas:
 views:
   - type: table
     name: Table
-    order: [file.name, category, cadence, due, last done, priority, status]
+    order: [file.name, category, frequency, due, last done, priority, status]
   - type: table
     name: Today
     filters:
@@ -40,15 +40,15 @@ views:
     name: Needs attention
     filters:
       and:
-        - 'cadence != null'
+        - 'frequency != null'
         - 'due == null'
-    order: [file.name, cadence, last done, priority]
+    order: [file.name, frequency, last done, priority]
   - type: table
     name: Sweep
     filters:
       and:
         - 'status == "done"'
-        - 'cadence == null'
+        - 'frequency == null'
     order: [file.name, category, last done, created]
 ```
 
@@ -72,7 +72,7 @@ the same numbers instead of recomputing them. The views answer the daily and
 weekly questions directly. Two are queues rather than schedules:
 `Needs attention` holds recurring tasks with no due date because they have
 never been completed, and `Sweep` holds finished one-time tasks waiting to be
-deleted. The `cadence == null` clause on `Sweep` is what keeps a recurring
+deleted. The `frequency == null` clause on `Sweep` is what keeps a recurring
 task that is wrongly sitting in `done` off the deletion list.
 
 ## Writing the file
@@ -115,12 +115,19 @@ task work are in `SKILL.md`.
   base sorts on a `formula.Untitled` that no `formulas:` block defines, and
   the remaining sort keys still apply as though it were not there. Neither
   case reports anything, so a sort that looks configured may not be.
-- **`== null` matches an empty property, not just a missing one.** The task
-  template writes `cadence:` with no value on every note, so `cadence == null`
-  is what correctly selects one-time tasks - a filter written to look for the
-  key's absence would match nothing. Verified against the live vault: the
-  `Sweep` view returns the finished one-time tasks and excludes a `done` task
-  carrying `cadence: weekly`.
+- **`== null` matches an empty property, but an empty *string* is not null.**
+  The template writes `frequency:` with no value, so `frequency == null`
+  correctly selects one-time tasks - a filter looking for the key's absence
+  would match nothing. But `frequency: ""`, which is what
+  `property:set value=""` writes, is **not** null and slips through the
+  filter. Verified on a scratch base against the live vault: a
+  `frequency != null` probe returned all 29 tasks while the one-time notes
+  held `""`, and the correct 11 once they held a bare key. Seed empty keys
+  from the template, never from `property:set`.
+- **A new property is invisible to `base:query` until a view lists it.**
+  Results are keyed by the view's `order:` columns, so a property written to
+  every note still reads back as absent until the base file names it. Update
+  the base before trying to verify a new field.
 - **Test formulas and filters on a scratch base, never the live one.**
   Create it, query it, delete it. A malformed formula is invisible until a
   query returns `Error: ...` in the column where a value should be.