feat: time-aware due dates, persistent undo, @return audit

Problem: Due dates had no time component, the undo stack was lost on
restart and stored in a separate file, and many public functions lacked
required @return annotations.

Solution: Add YYYY-MM-DDThh:mm support across parse, views, recur,
complete, and init with time-aware overdue checks. Merge the undo stack
into the task store JSON so a single file holds all state. Add @return
nil annotations to all 27 void public functions across every module.

lua/pending/recur.lua

@@ -80,20 +80,33 @@ function M.validate(spec)
   return M.parse(spec) ~= nil
 end
 
+---@param due string
+---@return string date_part
+---@return string? time_part
+local function split_datetime(due)
+  local dp, tp = due:match('^(.+)T(.+)$')
+  if dp then
+    return dp, tp
+  end
+  return due, nil
+end
+
 ---@param base_date string
 ---@param freq string
 ---@param interval integer
 ---@return string
 local function advance_date(base_date, freq, interval)
-  local y, m, d = base_date:match('^(%d+)-(%d+)-(%d+)$')
+  local date_part, time_part = split_datetime(base_date)
+  local y, m, d = date_part:match('^(%d+)-(%d+)-(%d+)$')
   local yn = tonumber(y) --[[@as integer]]
   local mn = tonumber(m) --[[@as integer]]
   local dn = tonumber(d) --[[@as integer]]
 
+  local result
   if freq == 'daily' then
-    return os.date('%Y-%m-%d', os.time({ year = yn, month = mn, day = dn + interval })) --[[@as string]]
+    result = os.date('%Y-%m-%d', os.time({ year = yn, month = mn, day = dn + interval })) --[[@as string]]
   elseif freq == 'weekly' then
-    return os.date('%Y-%m-%d', os.time({ year = yn, month = mn, day = dn + interval * 7 })) --[[@as string]]
+    result = os.date('%Y-%m-%d', os.time({ year = yn, month = mn, day = dn + interval * 7 })) --[[@as string]]
   elseif freq == 'monthly' then
     local new_m = mn + interval
     local new_y = yn
@@ -103,14 +116,20 @@ local function advance_date(base_date, freq, interval)
     end
     local last_day = os.date('*t', os.time({ year = new_y, month = new_m + 1, day = 0 })) --[[@as osdate]]
     local clamped_d = math.min(dn, last_day.day --[[@as integer]])
-    return os.date('%Y-%m-%d', os.time({ year = new_y, month = new_m, day = clamped_d })) --[[@as string]]
+    result = os.date('%Y-%m-%d', os.time({ year = new_y, month = new_m, day = clamped_d })) --[[@as string]]
   elseif freq == 'yearly' then
     local new_y = yn + interval
     local last_day = os.date('*t', os.time({ year = new_y, month = mn + 1, day = 0 })) --[[@as osdate]]
     local clamped_d = math.min(dn, last_day.day --[[@as integer]])
-    return os.date('%Y-%m-%d', os.time({ year = new_y, month = mn, day = clamped_d })) --[[@as string]]
+    result = os.date('%Y-%m-%d', os.time({ year = new_y, month = mn, day = clamped_d })) --[[@as string]]
+  else
+    return base_date
   end
-  return base_date
+
+  if time_part then
+    return result .. 'T' .. time_part
+  end
+  return result
 end
 
 ---@param base_date string
@@ -124,13 +143,16 @@ function M.next_due(base_date, spec, mode)
   end
 
   local today = os.date('%Y-%m-%d') --[[@as string]]
+  local _, time_part = split_datetime(base_date)
 
   if mode == 'completion' then
-    return advance_date(today, parsed.freq, parsed.interval)
+    local base = time_part and (today .. 'T' .. time_part) or today
+    return advance_date(base, parsed.freq, parsed.interval)
   end
 
   local next_date = advance_date(base_date, parsed.freq, parsed.interval)
-  while next_date <= today do
+  local compare_today = time_part and (today .. 'T' .. time_part) or today
+  while next_date <= compare_today do
     next_date = advance_date(next_date, parsed.freq, parsed.interval)
   end
   return next_date