Org QL agenda-like overview predicates

org-ql-overview.el

(require 'org-ql)
(declare-function org-ql--normalize-query "org-ql" t t)

(org-ql-defpred ap:agenda (&key to)
  "An agenda-like view, for use with other `ap:' predicates.
Includes tasks which with keywords:
  NOW (i.e. a current task)
  UNDERWAY (if not TO, or planned to TO)
  NEXT (if not TO, or planned to TO)
  other keywords (if scheduled to TO or within deadline warning)

Intended to be used alongside the `ap:stuck/unplanned' (in a
separate query).

The idea is that this \"agenda\" view shows tasks that are
current, scheduled for today, overdue, due today, due soon and
either unscheduled or scheduled up to today, or can be done
next (when not planned, or planned up to today).

The \"stuck/unplanned\" view shows PROJECT tasks that are
\"stuck\" (i.e. have no NEXT task and no planned tasks), as well
as non-PROJECT tasks which are not within a PROJECT and are not
planned (and any task within a project on HOLD is excluded).
\"Planned\" means having a SCHEDULED or DEADLINE property.

Together, these two views (ideally shown in adjacent windows)
have these purposes:

1. To ensure that no task or project is neglected.

2. Encourage the user to decide which tasks can be done next, as
well as when to do them (sometimes the hardest part).

3. Thereby make it easy to decide what to do now (making it
easier to get started).

Basically, the user chooses a task from the agenda view and does
it.  Then, when the agenda view is empty, the user moves to the
stuck/unplanned view, schedules tasks, reviews projects (marking
tasks as NEXT or planning them), and then returns to the agenda
view to choose the next task and continue working."
  :normalizers ((`(,predicate-names . ,(map :to))
                 `(and (todo)
                       (or (todo "NOW")
                           (and (todo "NEXT")
                                ,(if to
                                     ;; Agenda up to TO days ahead: only show NEXT items
                                     ;; that are planned up to that date or are unplanned
                                     `(or (planning :to ,to)
                                          (not (planning)))
                                   ;; Unlimited agenda: show all NEXT items.
                                   t))
                           (and (not (todo "NEXT"))
                                (or (scheduled :to ,to)
                                    (and (deadline auto)
                                         (or
                                          ;; Not scheduled but within deadline warning period.
                                          (not (scheduled))
                                          ;; Scheduled and due today or overdue.
                                          (deadline :to 0)))))
                           (and (todo "UNDERWAY")
                                (or
                                 ;; Not planned: show it.
                                 (not (planning))
                                 ;; Planned: show if planned today or in the past.
                                 (planning :to 0))))
                       (not (ancestors (todo "HOLD")))))))


;; Group-by:
;; ((:deadline future :scheduled future :order 99) (:todo ("NOW" "UNDERWAY")) (:deadline past :scheduled past) (:deadline today :scheduled today) (:todo "NEXT") (:auto-priority))

(org-ql-defpred ap:stuck/unplanned ()
  "Tasks that are \"stuck\" or unplanned."
  :normalizers ((`(,predicate-names)
                 '(and (or (and (todo "PROJECT")
                                (not (descendants
                                      (or (todo "NEXT")
                                          (and (not (done))
                                               (planning))))))
                           (and (todo)
                                (not (todo "PROJECT"))
                                (not (or (planning)
                                         (ancestors (todo "PROJECT"))))))
                       (not (ancestors (todo "HOLD")))))))

;; Group-by:
;; ((:todo "NOW") (:deadline past) (:deadline today) (:todo "NEXT") (:todo "UNDERWAY") (:auto-priority))