feat: omnifunc completion, recurring tasks, expanded date syntax (#27)

* feat(config): add recur_syntax and someday_date fields

Problem: the plugin needs configuration for the recurrence token name
and the sentinel date used by the `later`/`someday` named dates.

Solution: add `recur_syntax` (default 'rec') and `someday_date`
(default '9999-12-30') to pending.Config and the defaults table.

* feat(parse): expand date vocabulary with named dates

Problem: the date input only supports today, tomorrow, +Nd, and
weekday names, lacking relative offsets like weeks/months, period
boundaries, ordinals, month names, and backdating.

Solution: add yesterday, eod, sow/eow, som/eom, soq/eoq, soy/eoy,
+Nw, +Nm, -Nd, -Nw, ordinals (1st-31st), month names (jan-dec),
and later/someday to resolve_date(). Add tests for all new tokens.

* feat(recur): add recurrence parsing and next-date computation

Problem: the plugin has no concept of recurring tasks, which is
needed for habits and repeating deadlines.

Solution: add recur.lua with parse(), validate(), next_due(),
to_rrule(), and shorthand_list(). Supports named shorthands (daily,
weekdays, weekly, etc.), interval notation (Nd, Nw, Nm, Ny), raw
RRULE passthrough, and ! prefix for completion-based mode. Includes
day-clamping for month/year advancement.

* feat(store): add recur and recur_mode task fields

Problem: the task schema has no fields for storing recurrence rules.

Solution: add recur and recur_mode to the Task class, known_fields,
task_to_table, table_to_task, and the add() signature.

* feat(parse): add rec: inline token parsing

Problem: the buffer parser does not recognize recurrence tokens,
so users cannot set recurrence rules inline.

Solution: add recur_key() helper and rec: token parsing in body()
and command_add(), with ! prefix handling for completion-based mode
and validation via recur.validate().

* feat(diff): propagate recurrence through buffer reconciliation

Problem: the diff layer does not extract or apply recurrence fields,
so rec: tokens written in the buffer are silently ignored on :w.

Solution: add rec and rec_mode to ParsedEntry, extract them in
parse_buffer(), and pass them through create and update paths in
apply().

* feat(init): spawn next task on recurring task completion

Problem: completing a recurring task does not create the next
occurrence, and :Pending add does not pass recurrence fields.

Solution: in toggle_complete(), detect recurrence and spawn a new
pending task with the next due date. Wire rec/rec_mode through the
add() command path.

* feat(views): add recurrence to LineMeta

Problem: LineMeta does not carry recurrence info, so the buffer
layer cannot display recurrence indicators.

Solution: add recur field to LineMeta and populate it in both
category_view() and priority_view().

* feat(buffer): add PendingRecur highlight and recurrence virtual text

Problem: recurring tasks have no visual indicator in the buffer,
and the extmark logic uses a rigid if/elseif chain that does not
compose well with additional virtual text fields.

Solution: add PendingRecur highlight group linking to DiagnosticInfo.
Refactor apply_extmarks() to build virtual text parts dynamically,
appending category, recurrence indicator, and due date as separate
composable segments. Set omnifunc on the pending buffer.

* feat(complete): add omnifunc for cat:, due:, and rec: tokens

Problem: the pending buffer has no completion source, requiring
users to type metadata tokens from memory.

Solution: add complete.lua with an omnifunc that completes cat:
tokens from existing categories, due: tokens from the named date
vocabulary, and rec: tokens from recurrence shorthands.

* docs: document recurrence, expanded dates, omnifunc, new config

Problem: the vimdoc does not cover recurrence, expanded date syntax,
omnifunc completion, or the new config fields.

Solution: add DATE INPUT and RECURRENCE sections, update INLINE
METADATA, COMMANDS, CONFIGURATION, HIGHLIGHT GROUPS, HEALTH CHECK,
and DATA FORMAT. Expand the help popup with recurrence patterns and
new date tokens. Add recurrence validation to healthcheck.

* ci: fix

* fix(recur): resolve LuaLS type errors

Problem: LuaLS reported undefined-field for `_raw` on RecurSpec and
param-type-mismatch for `last_day.day` in `advance_date` because
`osdate.day` infers as `string|integer`.

Solution: Add `_raw` to the RecurSpec class annotation and cast
`last_day.day` to integer in both `math.min` call sites.

* refactor(init): remove help popup, use config-driven keymaps

Problem: Buffer-local keymaps were hardcoded with no way for users to
customize them. The g? help popup duplicated information already in the
vimdoc.

Solution: Remove show_help() and the g? mapping. Refactor
_setup_buf_mappings to read from cfg.keymaps, letting users override or
disable any buffer-local binding via vim.g.pending.

* feat(config): add keymaps table for buffer-local bindings

Problem: Users had no way to customize or disable buffer-local key
bindings in the pending buffer.

Solution: Add a pending.Keymaps class and keymaps field to
pending.Config with defaults for all eight buffer actions. Setting any
key to false disables that binding.

* feat(plugin): add Plug mappings for all buffer actions

Problem: Only five of nine buffer actions had <Plug> mappings, so users
could not bind close, undo, open-line, or open-line-above globally.

Solution: Add <Plug>(pending-close), <Plug>(pending-undo),
<Plug>(pending-open-line), and <Plug>(pending-open-line-above).

* docs: update mappings and config for keymaps and new Plug entries

Problem: Vimdoc still listed g? help popup, lacked documentation for
the four new <Plug> mappings, and had no keymaps config section.

Solution: Remove g? from mappings table, document all nine <Plug>
mappings, add keymaps table to the config example and field reference,
and note that buffer-local keys are configurable.

spec/complete_spec.lua

@@ -0,0 +1,171 @@
+require('spec.helpers')
+
+local config = require('pending.config')
+local store = require('pending.store')
+
+describe('complete', function()
+  local tmpdir
+  local complete = require('pending.complete')
+
+  before_each(function()
+    tmpdir = vim.fn.tempname()
+    vim.fn.mkdir(tmpdir, 'p')
+    vim.g.pending = { data_path = tmpdir .. '/tasks.json' }
+    config.reset()
+    store.unload()
+    store.load()
+  end)
+
+  after_each(function()
+    vim.fn.delete(tmpdir, 'rf')
+    vim.g.pending = nil
+    config.reset()
+  end)
+
+  describe('findstart', function()
+    it('returns column after colon for cat: prefix', function()
+      local bufnr = vim.api.nvim_create_buf(false, true)
+      vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, { '- [ ] task cat:Wo' })
+      vim.api.nvim_set_current_buf(bufnr)
+      vim.api.nvim_win_set_cursor(0, { 1, 16 })
+      local result = complete.omnifunc(1, '')
+      assert.are.equal(15, result)
+      vim.api.nvim_buf_delete(bufnr, { force = true })
+    end)
+
+    it('returns column after colon for due: prefix', function()
+      local bufnr = vim.api.nvim_create_buf(false, true)
+      vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, { '- [ ] task due:to' })
+      vim.api.nvim_set_current_buf(bufnr)
+      vim.api.nvim_win_set_cursor(0, { 1, 16 })
+      local result = complete.omnifunc(1, '')
+      assert.are.equal(15, result)
+      vim.api.nvim_buf_delete(bufnr, { force = true })
+    end)
+
+    it('returns column after colon for rec: prefix', function()
+      local bufnr = vim.api.nvim_create_buf(false, true)
+      vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, { '- [ ] task rec:we' })
+      vim.api.nvim_set_current_buf(bufnr)
+      vim.api.nvim_win_set_cursor(0, { 1, 16 })
+      local result = complete.omnifunc(1, '')
+      assert.are.equal(15, result)
+      vim.api.nvim_buf_delete(bufnr, { force = true })
+    end)
+
+    it('returns -1 for non-token position', function()
+      local bufnr = vim.api.nvim_create_buf(false, true)
+      vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, { '- [ ] some task ' })
+      vim.api.nvim_set_current_buf(bufnr)
+      vim.api.nvim_win_set_cursor(0, { 1, 14 })
+      local result = complete.omnifunc(1, '')
+      assert.are.equal(-1, result)
+      vim.api.nvim_buf_delete(bufnr, { force = true })
+    end)
+  end)
+
+  describe('completions', function()
+    it('returns existing categories for cat:', function()
+      store.add({ description = 'A', category = 'Work' })
+      store.add({ description = 'B', category = 'Home' })
+      store.add({ description = 'C', category = 'Work' })
+      local bufnr = vim.api.nvim_create_buf(false, true)
+      vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, { '- [ ] task cat: x' })
+      vim.api.nvim_set_current_buf(bufnr)
+      vim.api.nvim_win_set_cursor(0, { 1, 15 })
+      complete.omnifunc(1, '')
+      local result = complete.omnifunc(0, '')
+      local words = {}
+      for _, item in ipairs(result) do
+        table.insert(words, item.word)
+      end
+      assert.is_true(vim.tbl_contains(words, 'Work'))
+      assert.is_true(vim.tbl_contains(words, 'Home'))
+      vim.api.nvim_buf_delete(bufnr, { force = true })
+    end)
+
+    it('filters categories by base', function()
+      store.add({ description = 'A', category = 'Work' })
+      store.add({ description = 'B', category = 'Home' })
+      local bufnr = vim.api.nvim_create_buf(false, true)
+      vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, { '- [ ] task cat:W' })
+      vim.api.nvim_set_current_buf(bufnr)
+      vim.api.nvim_win_set_cursor(0, { 1, 15 })
+      complete.omnifunc(1, '')
+      local result = complete.omnifunc(0, 'W')
+      assert.are.equal(1, #result)
+      assert.are.equal('Work', result[1].word)
+      vim.api.nvim_buf_delete(bufnr, { force = true })
+    end)
+
+    it('returns named dates for due:', function()
+      local bufnr = vim.api.nvim_create_buf(false, true)
+      vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, { '- [ ] task due: x' })
+      vim.api.nvim_set_current_buf(bufnr)
+      vim.api.nvim_win_set_cursor(0, { 1, 15 })
+      complete.omnifunc(1, '')
+      local result = complete.omnifunc(0, '')
+      assert.is_true(#result > 0)
+      local words = {}
+      for _, item in ipairs(result) do
+        table.insert(words, item.word)
+      end
+      assert.is_true(vim.tbl_contains(words, 'today'))
+      assert.is_true(vim.tbl_contains(words, 'tomorrow'))
+      assert.is_true(vim.tbl_contains(words, 'eom'))
+      vim.api.nvim_buf_delete(bufnr, { force = true })
+    end)
+
+    it('filters dates by base prefix', function()
+      local bufnr = vim.api.nvim_create_buf(false, true)
+      vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, { '- [ ] task due:to' })
+      vim.api.nvim_set_current_buf(bufnr)
+      vim.api.nvim_win_set_cursor(0, { 1, 16 })
+      complete.omnifunc(1, '')
+      local result = complete.omnifunc(0, 'to')
+      local words = {}
+      for _, item in ipairs(result) do
+        table.insert(words, item.word)
+      end
+      assert.is_true(vim.tbl_contains(words, 'today'))
+      assert.is_true(vim.tbl_contains(words, 'tomorrow'))
+      assert.is_false(vim.tbl_contains(words, 'eom'))
+      vim.api.nvim_buf_delete(bufnr, { force = true })
+    end)
+
+    it('returns recurrence shorthands for rec:', function()
+      local bufnr = vim.api.nvim_create_buf(false, true)
+      vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, { '- [ ] task rec: x' })
+      vim.api.nvim_set_current_buf(bufnr)
+      vim.api.nvim_win_set_cursor(0, { 1, 15 })
+      complete.omnifunc(1, '')
+      local result = complete.omnifunc(0, '')
+      assert.is_true(#result > 0)
+      local words = {}
+      for _, item in ipairs(result) do
+        table.insert(words, item.word)
+      end
+      assert.is_true(vim.tbl_contains(words, 'daily'))
+      assert.is_true(vim.tbl_contains(words, 'weekly'))
+      assert.is_true(vim.tbl_contains(words, '!weekly'))
+      vim.api.nvim_buf_delete(bufnr, { force = true })
+    end)
+
+    it('filters recurrence by base prefix', function()
+      local bufnr = vim.api.nvim_create_buf(false, true)
+      vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, { '- [ ] task rec:we' })
+      vim.api.nvim_set_current_buf(bufnr)
+      vim.api.nvim_win_set_cursor(0, { 1, 16 })
+      complete.omnifunc(1, '')
+      local result = complete.omnifunc(0, 'we')
+      local words = {}
+      for _, item in ipairs(result) do
+        table.insert(words, item.word)
+      end
+      assert.is_true(vim.tbl_contains(words, 'weekly'))
+      assert.is_true(vim.tbl_contains(words, 'weekdays'))
+      assert.is_false(vim.tbl_contains(words, 'daily'))
+      vim.api.nvim_buf_delete(bufnr, { force = true })
+    end)
+  end)
+end)

spec/diff_spec.lua

@@ -69,6 +69,25 @@ describe('diff', function()
       assert.are.equal('Work', result[2].category)
     end)
 
+    it('extracts rec: token from buffer line', function()
+      local lines = {
+        '## Inbox',
+        '/1/- [ ] Take trash out rec:weekly',
+      }
+      local result = diff.parse_buffer(lines)
+      assert.are.equal('weekly', result[2].rec)
+    end)
+
+    it('extracts rec: with completion mode', function()
+      local lines = {
+        '## Inbox',
+        '/1/- [ ] Water plants rec:!daily',
+      }
+      local result = diff.parse_buffer(lines)
+      assert.are.equal('daily', result[2].rec)
+      assert.are.equal('completion', result[2].rec_mode)
+    end)
+
     it('inline due: token is parsed', function()
       local lines = {
         '## Inbox',
@@ -206,6 +225,60 @@ describe('diff', function()
       assert.is_nil(task.due)
     end)
 
+    it('stores recur field on new tasks from buffer', function()
+      local lines = {
+        '## Inbox',
+        '- [ ] Take out trash rec:weekly',
+      }
+      diff.apply(lines)
+      store.unload()
+      store.load()
+      local tasks = store.active_tasks()
+      assert.are.equal(1, #tasks)
+      assert.are.equal('weekly', tasks[1].recur)
+    end)
+
+    it('updates recur field when changed inline', function()
+      store.add({ description = 'Task', recur = 'daily' })
+      store.save()
+      local lines = {
+        '## Todo',
+        '/1/- [ ] Task rec:weekly',
+      }
+      diff.apply(lines)
+      store.unload()
+      store.load()
+      local task = store.get(1)
+      assert.are.equal('weekly', task.recur)
+    end)
+
+    it('clears recur when token removed from line', function()
+      store.add({ description = 'Task', recur = 'daily' })
+      store.save()
+      local lines = {
+        '## Todo',
+        '/1/- [ ] Task',
+      }
+      diff.apply(lines)
+      store.unload()
+      store.load()
+      local task = store.get(1)
+      assert.is_nil(task.recur)
+    end)
+
+    it('parses rec: with completion mode prefix', function()
+      local lines = {
+        '## Inbox',
+        '- [ ] Water plants rec:!weekly',
+      }
+      diff.apply(lines)
+      store.unload()
+      store.load()
+      local tasks = store.active_tasks()
+      assert.are.equal('weekly', tasks[1].recur)
+      assert.are.equal('completion', tasks[1].recur_mode)
+    end)
+
     it('clears priority when [N] is removed from buffer line', function()
       store.add({ description = 'Task name', priority = 1 })
       store.save()

spec/parse_spec.lua

@@ -154,6 +154,173 @@ describe('parse', function()
       local result = parse.resolve_date('')
       assert.is_nil(result)
     end)
+
+    it("returns yesterday's date for 'yesterday'", function()
+      local expected = os.date('%Y-%m-%d', os.time() - 86400)
+      local result = parse.resolve_date('yesterday')
+      assert.are.equal(expected, result)
+    end)
+
+    it("returns today's date for 'eod'", function()
+      local result = parse.resolve_date('eod')
+      assert.are.equal(os.date('%Y-%m-%d'), result)
+    end)
+
+    it('returns Monday of current week for sow', function()
+      local result = parse.resolve_date('sow')
+      assert.is_not_nil(result)
+      local y, m, d = result:match('^(%d+)-(%d+)-(%d+)$')
+      local t = os.time({ year = tonumber(y), month = tonumber(m), day = tonumber(d) })
+      local wday = os.date('*t', t).wday
+      assert.are.equal(2, wday)
+    end)
+
+    it('returns Sunday of current week for eow', function()
+      local result = parse.resolve_date('eow')
+      assert.is_not_nil(result)
+      local y, m, d = result:match('^(%d+)-(%d+)-(%d+)$')
+      local t = os.time({ year = tonumber(y), month = tonumber(m), day = tonumber(d) })
+      local wday = os.date('*t', t).wday
+      assert.are.equal(1, wday)
+    end)
+
+    it('returns first day of current month for som', function()
+      local today = os.date('*t') --[[@as osdate]]
+      local expected = string.format('%04d-%02d-01', today.year, today.month)
+      local result = parse.resolve_date('som')
+      assert.are.equal(expected, result)
+    end)
+
+    it('returns last day of current month for eom', function()
+      local today = os.date('*t') --[[@as osdate]]
+      local expected =
+        os.date('%Y-%m-%d', os.time({ year = today.year, month = today.month + 1, day = 0 }))
+      local result = parse.resolve_date('eom')
+      assert.are.equal(expected, result)
+    end)
+
+    it('returns first day of current quarter for soq', function()
+      local today = os.date('*t') --[[@as osdate]]
+      local q = math.ceil(today.month / 3)
+      local first_month = (q - 1) * 3 + 1
+      local expected = string.format('%04d-%02d-01', today.year, first_month)
+      local result = parse.resolve_date('soq')
+      assert.are.equal(expected, result)
+    end)
+
+    it('returns last day of current quarter for eoq', function()
+      local today = os.date('*t') --[[@as osdate]]
+      local q = math.ceil(today.month / 3)
+      local last_month = q * 3
+      local expected =
+        os.date('%Y-%m-%d', os.time({ year = today.year, month = last_month + 1, day = 0 }))
+      local result = parse.resolve_date('eoq')
+      assert.are.equal(expected, result)
+    end)
+
+    it('returns Jan 1 of current year for soy', function()
+      local today = os.date('*t') --[[@as osdate]]
+      local expected = string.format('%04d-01-01', today.year)
+      local result = parse.resolve_date('soy')
+      assert.are.equal(expected, result)
+    end)
+
+    it('returns Dec 31 of current year for eoy', function()
+      local today = os.date('*t') --[[@as osdate]]
+      local expected = string.format('%04d-12-31', today.year)
+      local result = parse.resolve_date('eoy')
+      assert.are.equal(expected, result)
+    end)
+
+    it('resolves +2w to 14 days from today', function()
+      local today = os.date('*t') --[[@as osdate]]
+      local expected = os.date(
+        '%Y-%m-%d',
+        os.time({ year = today.year, month = today.month, day = today.day + 14 })
+      )
+      local result = parse.resolve_date('+2w')
+      assert.are.equal(expected, result)
+    end)
+
+    it('resolves +3m to 3 months from today', function()
+      local today = os.date('*t') --[[@as osdate]]
+      local expected = os.date(
+        '%Y-%m-%d',
+        os.time({ year = today.year, month = today.month + 3, day = today.day })
+      )
+      local result = parse.resolve_date('+3m')
+      assert.are.equal(expected, result)
+    end)
+
+    it('resolves -2d to 2 days ago', function()
+      local today = os.date('*t') --[[@as osdate]]
+      local expected = os.date(
+        '%Y-%m-%d',
+        os.time({ year = today.year, month = today.month, day = today.day - 2 })
+      )
+      local result = parse.resolve_date('-2d')
+      assert.are.equal(expected, result)
+    end)
+
+    it('resolves -1w to 7 days ago', function()
+      local today = os.date('*t') --[[@as osdate]]
+      local expected = os.date(
+        '%Y-%m-%d',
+        os.time({ year = today.year, month = today.month, day = today.day - 7 })
+      )
+      local result = parse.resolve_date('-1w')
+      assert.are.equal(expected, result)
+    end)
+
+    it("resolves 'later' to someday_date", function()
+      local result = parse.resolve_date('later')
+      assert.are.equal('9999-12-30', result)
+    end)
+
+    it("resolves 'someday' to someday_date", function()
+      local result = parse.resolve_date('someday')
+      assert.are.equal('9999-12-30', result)
+    end)
+
+    it('resolves 15th to next 15th of month', function()
+      local result = parse.resolve_date('15th')
+      assert.is_not_nil(result)
+      local _, _, d = result:match('^(%d+)-(%d+)-(%d+)$')
+      assert.are.equal('15', d)
+    end)
+
+    it('resolves 1st to next 1st of month', function()
+      local result = parse.resolve_date('1st')
+      assert.is_not_nil(result)
+      local _, _, d = result:match('^(%d+)-(%d+)-(%d+)$')
+      assert.are.equal('01', d)
+    end)
+
+    it('resolves jan to next January 1st', function()
+      local today = os.date('*t') --[[@as osdate]]
+      local result = parse.resolve_date('jan')
+      assert.is_not_nil(result)
+      local y, m, d = result:match('^(%d+)-(%d+)-(%d+)$')
+      assert.are.equal('01', m)
+      assert.are.equal('01', d)
+      if today.month >= 1 then
+        assert.are.equal(tostring(today.year + 1), y)
+      end
+    end)
+
+    it('resolves dec to next December 1st', function()
+      local today = os.date('*t') --[[@as osdate]]
+      local result = parse.resolve_date('dec')
+      assert.is_not_nil(result)
+      local y, m, d = result:match('^(%d+)-(%d+)-(%d+)$')
+      assert.are.equal('12', m)
+      assert.are.equal('01', d)
+      if today.month >= 12 then
+        assert.are.equal(tostring(today.year + 1), y)
+      else
+        assert.are.equal(tostring(today.year), y)
+      end
+    end)
   end)
 
   describe('command_add', function()

spec/recur_spec.lua

@@ -0,0 +1,223 @@
+require('spec.helpers')
+
+describe('recur', function()
+  local recur = require('pending.recur')
+
+  describe('parse', function()
+    it('parses daily', function()
+      local r = recur.parse('daily')
+      assert.are.equal('daily', r.freq)
+      assert.are.equal(1, r.interval)
+      assert.is_false(r.from_completion)
+    end)
+
+    it('parses weekdays', function()
+      local r = recur.parse('weekdays')
+      assert.are.equal('weekly', r.freq)
+      assert.are.same({ 'MO', 'TU', 'WE', 'TH', 'FR' }, r.byday)
+    end)
+
+    it('parses weekly', function()
+      local r = recur.parse('weekly')
+      assert.are.equal('weekly', r.freq)
+      assert.are.equal(1, r.interval)
+    end)
+
+    it('parses biweekly', function()
+      local r = recur.parse('biweekly')
+      assert.are.equal('weekly', r.freq)
+      assert.are.equal(2, r.interval)
+    end)
+
+    it('parses monthly', function()
+      local r = recur.parse('monthly')
+      assert.are.equal('monthly', r.freq)
+      assert.are.equal(1, r.interval)
+    end)
+
+    it('parses quarterly', function()
+      local r = recur.parse('quarterly')
+      assert.are.equal('monthly', r.freq)
+      assert.are.equal(3, r.interval)
+    end)
+
+    it('parses yearly', function()
+      local r = recur.parse('yearly')
+      assert.are.equal('yearly', r.freq)
+      assert.are.equal(1, r.interval)
+    end)
+
+    it('parses annual as yearly', function()
+      local r = recur.parse('annual')
+      assert.are.equal('yearly', r.freq)
+    end)
+
+    it('parses 3d as every 3 days', function()
+      local r = recur.parse('3d')
+      assert.are.equal('daily', r.freq)
+      assert.are.equal(3, r.interval)
+    end)
+
+    it('parses 2w as biweekly', function()
+      local r = recur.parse('2w')
+      assert.are.equal('weekly', r.freq)
+      assert.are.equal(2, r.interval)
+    end)
+
+    it('parses 6m as every 6 months', function()
+      local r = recur.parse('6m')
+      assert.are.equal('monthly', r.freq)
+      assert.are.equal(6, r.interval)
+    end)
+
+    it('parses 2y as every 2 years', function()
+      local r = recur.parse('2y')
+      assert.are.equal('yearly', r.freq)
+      assert.are.equal(2, r.interval)
+    end)
+
+    it('parses ! prefix as completion-based', function()
+      local r = recur.parse('!weekly')
+      assert.are.equal('weekly', r.freq)
+      assert.is_true(r.from_completion)
+    end)
+
+    it('parses raw RRULE fragment', function()
+      local r = recur.parse('FREQ=MONTHLY;BYDAY=1MO')
+      assert.is_not_nil(r)
+    end)
+
+    it('returns nil for invalid input', function()
+      assert.is_nil(recur.parse(''))
+      assert.is_nil(recur.parse('garbage'))
+      assert.is_nil(recur.parse('0d'))
+    end)
+
+    it('is case insensitive', function()
+      local r = recur.parse('Weekly')
+      assert.are.equal('weekly', r.freq)
+    end)
+  end)
+
+  describe('validate', function()
+    it('returns true for valid specs', function()
+      assert.is_true(recur.validate('daily'))
+      assert.is_true(recur.validate('2w'))
+      assert.is_true(recur.validate('!monthly'))
+    end)
+
+    it('returns false for invalid specs', function()
+      assert.is_false(recur.validate('garbage'))
+      assert.is_false(recur.validate(''))
+    end)
+  end)
+
+  describe('next_due', function()
+    it('advances daily by 1 day', function()
+      local result = recur.next_due('2099-03-01', 'daily', 'scheduled')
+      assert.are.equal('2099-03-02', result)
+    end)
+
+    it('advances weekly by 7 days', function()
+      local result = recur.next_due('2099-03-01', 'weekly', 'scheduled')
+      assert.are.equal('2099-03-08', result)
+    end)
+
+    it('advances monthly and clamps day', function()
+      local result = recur.next_due('2099-01-31', 'monthly', 'scheduled')
+      assert.are.equal('2099-02-28', result)
+    end)
+
+    it('advances yearly and handles leap year', function()
+      local result = recur.next_due('2096-02-29', 'yearly', 'scheduled')
+      assert.are.equal('2097-02-28', result)
+    end)
+
+    it('advances biweekly by 14 days', function()
+      local result = recur.next_due('2099-03-01', 'biweekly', 'scheduled')
+      assert.are.equal('2099-03-15', result)
+    end)
+
+    it('advances quarterly by 3 months', function()
+      local result = recur.next_due('2099-01-15', 'quarterly', 'scheduled')
+      assert.are.equal('2099-04-15', result)
+    end)
+
+    it('scheduled mode skips to future if overdue', function()
+      local result = recur.next_due('2020-01-01', 'yearly', 'scheduled')
+      local today = os.date('%Y-%m-%d') --[[@as string]]
+      assert.is_true(result > today)
+    end)
+
+    it('completion mode advances from today', function()
+      local today = os.date('*t') --[[@as osdate]]
+      local expected = os.date(
+        '%Y-%m-%d',
+        os.time({
+          year = today.year,
+          month = today.month,
+          day = today.day + 7,
+        })
+      )
+      local result = recur.next_due('2020-01-01', 'weekly', 'completion')
+      assert.are.equal(expected, result)
+    end)
+
+    it('advances 3d by 3 days', function()
+      local result = recur.next_due('2099-06-10', '3d', 'scheduled')
+      assert.are.equal('2099-06-13', result)
+    end)
+  end)
+
+  describe('to_rrule', function()
+    it('converts daily', function()
+      assert.are.equal('RRULE:FREQ=DAILY', recur.to_rrule('daily'))
+    end)
+
+    it('converts weekly', function()
+      assert.are.equal('RRULE:FREQ=WEEKLY', recur.to_rrule('weekly'))
+    end)
+
+    it('converts biweekly with interval', function()
+      assert.are.equal('RRULE:FREQ=WEEKLY;INTERVAL=2', recur.to_rrule('biweekly'))
+    end)
+
+    it('converts weekdays with BYDAY', function()
+      assert.are.equal('RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR', recur.to_rrule('weekdays'))
+    end)
+
+    it('converts monthly', function()
+      assert.are.equal('RRULE:FREQ=MONTHLY', recur.to_rrule('monthly'))
+    end)
+
+    it('converts quarterly with interval', function()
+      assert.are.equal('RRULE:FREQ=MONTHLY;INTERVAL=3', recur.to_rrule('quarterly'))
+    end)
+
+    it('converts yearly', function()
+      assert.are.equal('RRULE:FREQ=YEARLY', recur.to_rrule('yearly'))
+    end)
+
+    it('converts 2w with interval', function()
+      assert.are.equal('RRULE:FREQ=WEEKLY;INTERVAL=2', recur.to_rrule('2w'))
+    end)
+
+    it('prefixes raw RRULE fragment', function()
+      assert.are.equal('RRULE:FREQ=MONTHLY;BYDAY=1MO', recur.to_rrule('FREQ=MONTHLY;BYDAY=1MO'))
+    end)
+
+    it('returns empty string for invalid spec', function()
+      assert.are.equal('', recur.to_rrule('garbage'))
+    end)
+  end)
+
+  describe('shorthand_list', function()
+    it('returns a list of named shorthands', function()
+      local list = recur.shorthand_list()
+      assert.is_true(#list >= 8)
+      assert.is_true(vim.tbl_contains(list, 'daily'))
+      assert.is_true(vim.tbl_contains(list, 'weekly'))
+      assert.is_true(vim.tbl_contains(list, 'monthly'))
+    end)
+  end)
+end)

spec/store_spec.lua

@@ -196,6 +196,41 @@ describe('store', function()
     end)
   end)
 
+  describe('recurrence fields', function()
+    it('persists recur and recur_mode through round-trip', function()
+      store.load()
+      store.add({ description = 'Recurring', recur = 'weekly', recur_mode = 'scheduled' })
+      store.save()
+      store.unload()
+      store.load()
+      local task = store.get(1)
+      assert.are.equal('weekly', task.recur)
+      assert.are.equal('scheduled', task.recur_mode)
+    end)
+
+    it('persists recur without recur_mode', function()
+      store.load()
+      store.add({ description = 'Simple recur', recur = 'daily' })
+      store.save()
+      store.unload()
+      store.load()
+      local task = store.get(1)
+      assert.are.equal('daily', task.recur)
+      assert.is_nil(task.recur_mode)
+    end)
+
+    it('omits recur fields when not set', function()
+      store.load()
+      store.add({ description = 'No recur' })
+      store.save()
+      store.unload()
+      store.load()
+      local task = store.get(1)
+      assert.is_nil(task.recur)
+      assert.is_nil(task.recur_mode)
+    end)
+  end)
+
   describe('active_tasks', function()
     it('excludes deleted tasks', function()
       store.load()

spec/views_spec.lua

@@ -204,6 +204,30 @@ describe('views', function()
       assert.is_falsy(task_meta.overdue)
     end)
 
+    it('includes recur in LineMeta for recurring tasks', function()
+      store.add({ description = 'Recurring', category = 'Inbox', recur = 'weekly' })
+      local _, meta = views.category_view(store.active_tasks())
+      local task_meta
+      for _, m in ipairs(meta) do
+        if m.type == 'task' then
+          task_meta = m
+        end
+      end
+      assert.are.equal('weekly', task_meta.recur)
+    end)
+
+    it('has nil recur in LineMeta for non-recurring tasks', function()
+      store.add({ description = 'Normal', category = 'Inbox' })
+      local _, meta = views.category_view(store.active_tasks())
+      local task_meta
+      for _, m in ipairs(meta) do
+        if m.type == 'task' then
+          task_meta = m
+        end
+      end
+      assert.is_nil(task_meta.recur)
+    end)
+
     it('respects category_order when set', function()
       vim.g.pending = { data_path = tmpdir .. '/tasks.json', category_order = { 'Work', 'Inbox' } }
       config.reset()
@@ -399,5 +423,29 @@ describe('views', function()
       end
       assert.is_falsy(task_meta.overdue)
     end)
+
+    it('includes recur in LineMeta for recurring tasks', function()
+      store.add({ description = 'Recurring', category = 'Inbox', recur = 'daily' })
+      local _, meta = views.priority_view(store.active_tasks())
+      local task_meta
+      for _, m in ipairs(meta) do
+        if m.type == 'task' then
+          task_meta = m
+        end
+      end
+      assert.are.equal('daily', task_meta.recur)
+    end)
+
+    it('has nil recur in LineMeta for non-recurring tasks', function()
+      store.add({ description = 'Normal', category = 'Inbox' })
+      local _, meta = views.priority_view(store.active_tasks())
+      local task_meta
+      for _, m in ipairs(meta) do
+        if m.type == 'task' then
+          task_meta = m
+        end
+      end
+      assert.is_nil(task_meta.recur)
+    end)
   end)
 end)