org-agenda-list-stuck-projects and nested projects

[Ross Patterson <me@rpatterson.net>]

One of the things I love about org-mode is that it's generally hierarchy
agnostic which is to say it doesn't care what level or depth entries are
with regards to the functionality org-mode provides with entries (TODOs,
Dates and times, tags, etc.).

Many of the projects I'd like to manage with org-mode are fairly large
and as such I'd like to make use of org-mode's heirarchical agnosticism
to factor my projects into nested projects arbitrary depth.  This is
supported very well by the rest of org-mode, just not the stuck projects
agenda view.

I find that view very valuable, but if I have a project with lots of
branches that can move in parallel and one of those branches is stuck
but another isn't stuck, then the stuck projects report doesn't reflect
this assuming that if one branch isn't stuck then the project isn't
stuck.  Since the project is very large, that means I have to inspect
the whole tree to figure out what might be stuck.  The only workaround
with the current implementation is that anytime I have a
project/sub-project/branch lower than LEVEL=2 that I need to be able to
review, then I have to break it out to a LEVEL=2 headline.  This creates
a negative feedback which will probably result in me not using the stuck
projects view and probably insufficiently reviewing my projects.

What I'd like is an agenda view like the stuck projects view but rather
than omitting any project that has any active TODO's all the way up the
hierarchy, it will only omit headlines that have active TODO's among its
immediate children.

If I start with a test.org file like so:

    * Testing
    ** Stuck Project at Level 2
    *** Sub-project at Level 3
    **** DONE bar
    *** Sub-project 2 at Level 3

And customize org-stuck-projects to remove the LEVEL=2 restriction like
so:

    (setq org-stuck-projects '("/-DONE" ("TODO") nil ""))

And finally customize the org-tags-match-list-sublevels to allow tags
matching to descend.

Then if I open test.org and do "C-c a < #" I get:

    List of stuck projects:
      test:       .Stuck Project at Level 2
      test:       ..Sub-project at Level 3
      test:       ..Sub-project 2 at Level 3

Then if I re-activate the bar heading by putting it in the TODO state:

    * Testing
    ** Stuck Project at Level 2
    *** Sub-project at Level 3
    **** TODO bar
    *** Sub-project 2 at Level 3

I get an empty list:

    List of stuck projects:

I'd like a list with the sub-heading that is still stuck:

    List of stuck projects:
      test:       .Stuck Project at Level 2
      test:       ..Sub-project 2 at Level 3

I tried modifying the org-agenda-list-stuck-projects function by
implementing an org-agenda-skip-function that only skips the heading
and not the whole subtree:

    (defun org-agenda-skip-entry-when-regexp-matches ()
      "Checks if the current entry contains match for `org-agenda-skip-regexp'.
    If yes, it returns the end position of this entry, causing agenda
    commands to skip this entry.  This is a function that can be put
    into `org-agenda-skip-function' for the duration of a command."
      (org-agenda-skip-if nil '(regexp org-agenda-skip-regexp)))

Then I replaced the org-agenda-skip-function set in
org-agenda-list-stuck-projects by replacing:

  (let* ((org-agenda-skip-function 'org-agenda-skip-subtree-when-regexp-matches)

with:

  (let* ((org-agenda-skip-function 'org-agenda-skip-entry-when-regexp-matches)

But that gets me:

    List of stuck projects:
      test:       .Stuck Project at Level 2
      test:       ..Sub-project at Level 3
      test:       ...TODO bar
      test:       ..Sub-project 2 at Level 3

I'm new to the internals of org-mode.  Can anyone help me figure out
what's wrong with my attempted solution here?

Ross