whatnext 2.0__tar.gz → 2.1__tar.gz

{whatnext-2.0 → whatnext-2.1}/CHANGELOG.md

@@ -1,6 +1,15 @@
 # Changelog
 
 
+## [v2.0] - 2026-02-09
+
+Added `@queue` directive show only one task at a time, for simple sequential
+work that doesn't need to be split across files using `@after`.
+
+**Fixes:**
+- Annotation and priority indicators were not appearing for headerless files
+
+
 ## [v2.0] - 2026-01-28
 
 **Breaking change:** `whatnext` now ignores tasks and headers within

{whatnext-2.0 → whatnext-2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: whatnext
-Version: 2.0
+Version: 2.1
 Summary: A lister of tasks found in Markdown files
 Project-URL: Homepage, https://github.com/norm/whatnext
 Project-URL: Repository, https://github.com/norm/whatnext

{whatnext-2.0 → whatnext-2.1}/docs/index.md

@@ -56,6 +56,9 @@ and sections can have [annotations included](annotations.md).
 If a task has a dependency on other tasks, such that it cannot be done in any
 order, you can [defer tasks](deferring.md) until all/some other tasks are complete.
 
+For sequential work where only one task can be done at a time, you can
+[limit output](sequential.md) to the next open task in the file.
+
 If you need to exclude out some Markdown files for any reason, there are
 [two ways to do that](exclusions.md).
 

whatnext-2.1/docs/sequential.md

@@ -0,0 +1,26 @@
+# Sequential tasks
+
+For simpler work that is done sequentially, either because they have to be
+done one-after-the-other, or because they represent larger blocks that are
+not broken down into subtasks, add `@queue` to the file:
+
+```markdown
+@queue
+
+- [ ] backup production database
+- [ ] run migration to add audit columns
+- [ ] backfill audit data from logs
+```
+
+When querying, [priorities](prioritisation.md) and [deadlines](deadlines.md)
+will apply as usual within the file, and only the most important or
+top-most task is presented. If any tasks are marked as in-progress,
+they will all be shown.
+
+```bash
+(computer)% whatnext
+auditing.md:
+    - [ ] backup production database
+```
+
+When querying with `--all` or `--summary` arguments, all tasks are presented.

whatnext-2.1/example/projects/fountain.md

@@ -0,0 +1,8 @@
+Make the Philosopher's Stone.
+
+@queue
+
+- [ ] nigredo, the blackening or melanosis
+- [ ] albedo, the whitening or leucosis
+- [ ] citrinitas, the yellowing or xanthosis
+- [ ] rubedo, the reddening, purpling, or iosis

whatnext-2.1/tasks/listing.md

@@ -0,0 +1,11 @@
+**One at a time task visibility.**
+For sequential checklists where you have tasks that can/should only be
+done one at a time, but don't want to make multiple files for one task
+to set up `@after` ordering.
+
+List:
+- all `[/]` in-progress tasks (there may be multiple)
+- if none, the highest priority open task
+- if none, the highest priority blocked task
+
+- [X] Add `@queue` directive to files, limiting a file's output to one(ish)

{whatnext-2.0 → whatnext-2.1}/tasks.md

@@ -15,3 +15,5 @@ New features go in `./tasks/[feature].md`.
 > next: error: unrecognized arguments: -e something
 - [X] headers in fenceblocks are used as headers and should not be -- should whatnext ignore tasks in fenceblocks too?
 - [X] `--summary --relative` with multiple states uses the same character for the second selected state and the unselected complement
+- [X] annotations in `whatnext` blocks don't appear in output unless preceded by a heading
+- [X] overdue/high/medium/imminent comments are not appearing when there are no headings

{whatnext-2.0 → whatnext-2.1}/tests/edit.bats

@@ -65,6 +65,7 @@ setup() {
         +6 example/projects/harvest.md
         +5 example/tasks.md
         +7 example/projects/curtain.md
+        +5 example/projects/fountain.md
         +3 example/projects/tinsel.md
         +3 example/archived/projects/tangerine.md
         EOF

whatnext-2.1/tests/headerless/annotation.md

@@ -0,0 +1,5 @@
+```whatnext
+This annotation should appear even without a heading.
+```
+
+- [ ] a task without heading

whatnext-2.1/tests/headerless/deadline.md

@@ -0,0 +1 @@
+- [ ] an overdue task without heading @2020-01-01

{whatnext-2.0 → whatnext-2.1}/tests/list.bats

@@ -57,6 +57,8 @@ function setup {
         projects/curtain.md:
             # Project Curtain / Final bow
             - [ ] Take a bow
+        projects/fountain.md:
+            - [ ] nigredo, the blackening or melanosis
         projects/harvest.md:
             # Project Harvest
             - [/] turn compost heap
@@ -71,7 +73,7 @@ function setup {
     diff -u <(echo "$expected_output") <(echo "$output")
 
     # no extraneous blank lines at the end
-    [ $(WHATNEXT_TODAY=2025-12-25 whatnext 2>/dev/null | wc -l) -eq 56 ]
+    [ $(WHATNEXT_TODAY=2025-12-25 whatnext 2>/dev/null | wc -l) -eq 58 ]
 
     [ $status -eq 0 ]
 }
@@ -117,6 +119,9 @@ function setup {
         projects/curtain.md:
             # Project Curtain / Final bow
             - [ ] Take a bow
+        projects/fountain.md:
+            - [ ] nigredo, the blackening or
+                  melanosis
         projects/harvest.md:
             # Project Harvest
             - [/] turn compost heap
@@ -179,6 +184,11 @@ function setup {
             # Project Curtain / Close the theatre
             - [ ] Escort everyone out
             - [ ] Shut up shop
+        projects/fountain.md:
+            - [ ] nigredo, the blackening or melanosis
+            - [ ] albedo, the whitening or leucosis
+            - [ ] citrinitas, the yellowing or xanthosis
+            - [ ] rubedo, the reddening, purpling, or iosis
         projects/harvest.md:
             # Project Harvest
             - [/] turn compost heap
@@ -242,6 +252,8 @@ function setup {
             # Project Harvest / MEDIUM
             - [ ] buy copper tape for slugs
 
+        fountain.md:
+            - [ ] nigredo, the blackening or melanosis
         harvest.md:
             # Project Harvest
             - [/] turn compost heap
@@ -662,3 +674,34 @@ function setup {
 
     [ "$found_different" -eq 1 ]
 }
+
+@test "headerless file shows annotation" {
+    run --separate-stderr \
+        whatnext \
+            ../tests/headerless/annotation.md
+
+    expected_output=$(sed -e 's/^        //' <<"        EOF"
+        ../tests/headerless/annotation.md:
+            This annotation should appear even without a heading.
+            - [ ] a task without heading
+        EOF
+    )
+    diff -u <(echo "$expected_output") <(echo "$output")
+    [ $status -eq 0 ]
+}
+
+@test "headerless file shows priority" {
+    WHATNEXT_TODAY=2025-01-01 \
+        run --separate-stderr \
+            whatnext \
+                ../tests/headerless/deadline.md
+
+    expected_output=$(sed -e 's/^        //' <<"        EOF"
+        ../tests/headerless/deadline.md:
+            # OVERDUE 5y
+            - [ ] an overdue task without heading
+        EOF
+    )
+    diff -u <(echo "$expected_output") <(echo "$output")
+    [ $status -eq 0 ]
+}

{whatnext-2.0 → whatnext-2.1}/tests/matching.bats

@@ -161,6 +161,8 @@ function setup {
             # Project Harvest / MEDIUM
             - [ ] buy copper tape for slugs
 
+        fountain.md:
+            - [ ] nigredo, the blackening or melanosis
         harvest.md:
             # Project Harvest
             - [/] turn compost heap
@@ -224,6 +226,11 @@ function setup {
             # Project Curtain / Close the theatre
             - [ ] Escort everyone out
             - [ ] Shut up shop
+        projects/fountain.md:
+            - [ ] nigredo, the blackening or melanosis
+            - [ ] albedo, the whitening or leucosis
+            - [ ] citrinitas, the yellowing or xanthosis
+            - [ ] rubedo, the reddening, purpling, or iosis
         projects/harvest.md:
             # Project Harvest
             - [/] turn compost heap
@@ -315,6 +322,8 @@ function setup {
             # Project Harvest / MEDIUM
             - [ ] buy copper tape for slugs
 
+        fountain.md:
+            - [ ] nigredo, the blackening or melanosis
         harvest.md:
             # Project Harvest
             - [/] turn compost heap

whatnext-2.1/tests/queue/all-complete.md

@@ -0,0 +1,8 @@
+@queue
+
+```whatnext
+Nothing shown when all complete.
+```
+
+- [X] done
+- [#] cancelled

whatnext-2.1/tests/queue/blocked.md

@@ -0,0 +1,9 @@
+@queue
+
+```whatnext
+Falls back to blocked when no open tasks.
+```
+
+- [X] completed task
+- [#] cancelled task
+- [<] blocked task

whatnext-2.1/tests/queue/in-progress.md

@@ -0,0 +1,11 @@
+@queue
+
+```whatnext
+More than one in-progress tasks shows all.
+```
+
+- [/] first in progress
+- [/] second in progress
+- [ ] first open
+- [ ] second open
+- [ ] third open

whatnext-2.1/tests/queue/normal.md

@@ -0,0 +1,6 @@
+```whatnext
+A normal task file with multiple tasks.
+```
+
+- [ ] first task
+- [ ] second task

whatnext-2.1/tests/queue/prioritised.md

@@ -0,0 +1,9 @@
+@queue
+
+```whatnext
+Highest priority open task shown.
+```
+
+- [ ] normal priority task
+- [ ] **high priority task**
+- [ ] _medium priority task_

whatnext-2.1/tests/queue.bats

@@ -0,0 +1,53 @@
+bats_require_minimum_version 1.5.0
+
+@test "a @queue file shows only one task" {
+    WHATNEXT_TODAY=2025-01-01 \
+        run --separate-stderr \
+            whatnext \
+                example/projects/fountain.md
+
+    expected_output=$(sed -e 's/^        //' <<-'EOF'
+        example/projects/fountain.md:
+            - [ ] nigredo, the blackening or melanosis
+	EOF
+    )
+    diff -u <(echo "$expected_output") <(echo "$output")
+    [ $status -eq 0 ]
+}
+
+@test "a directory listing" {
+    run --separate-stderr \
+        whatnext \
+            tests/queue
+
+    expected_output=$(sed -e 's/^        //' <<-'EOF'
+        prioritised.md:
+            # HIGH
+            Highest priority open task shown.
+            - [ ] high priority task
+
+        blocked.md:
+            Falls back to blocked when no open tasks.
+            - [<] blocked task
+        in-progress.md:
+            More than one in-progress tasks shows all.
+            - [/] first in progress
+            - [/] second in progress
+        normal.md:
+            A normal task file with multiple tasks.
+            - [ ] first task
+            - [ ] second task
+	EOF
+    )
+    diff -u <(echo "$expected_output") <(echo "$output")
+    [ $status -eq 0 ]
+}
+
+@test "queue shows nothing when all complete" {
+    run --separate-stderr \
+        whatnext \
+            tests/queue/all-complete.md
+
+    [ "$output" = "" ]
+    [ $status -eq 0 ]
+}

{whatnext-2.0 → whatnext-2.1}/tests/summary.bats

@@ -11,14 +11,15 @@ function setup {
                 --summary
 
     expected_output=$(sed -e 's/^        //' <<"        EOF"
-                                                           B P  O
-        ░░░░░░░░░░░░░░░░░░░░░░░░                           0 0  3  tasks.md
-        ░░░░░░░░                                           0 0  1  projects/curtain.md
-        ▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  0 1  5  projects/harvest.md
-        ▚▚▚▚▚▚▚▚▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░░░                  1 1  2  projects/obelisk.md
-        ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░          0 0  5  projects/tinsel.md
-                                                           ──────
-                                                           1 2 16  19, of 29 total
+                                                          B P  O
+        ░░░░░░░░░░░░░░░░░░░░░░░░                          0 0  3  tasks.md
+        ░░░░░░░░                                          0 0  1  projects/curtain.md
+        ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░                  0 0  4  projects/fountain.md
+        ▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  0 1  5  projects/harvest.md
+        ▚▚▚▚▚▚▚▚▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░░                  1 1  2  projects/obelisk.md
+        ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░          0 0  5  projects/tinsel.md
+                                                          ──────
+                                                          1 2 20  23, of 33 total
 
         ▚ Blocked  ▓ Partial  ░ Open
         EOF
@@ -38,12 +39,13 @@ function setup {
                                             C D B P  O
         ░░░░░░░░░░░░░                       0 0 0 0  3  tasks.md
         ░░░░░░░░░░░░░░░░░                   0 0 0 0  4  projects/curtain.md
+        ░░░░░░░░░░░░░░░░░                   0 0 0 0  4  projects/fountain.md
         ▚▚▚▚████▒▒▒▒▒░░░░░░░░░░░░░░░░░░░░░  1 1 0 1  5  projects/harvest.md
         ████▓▓▓▓▒▒▒▒▒░░░░░░░░               0 1 1 1  2  projects/obelisk.md
         ░░░░░░░░░░░░░░░░░░░░░               0 0 0 0  5  projects/tinsel.md
         ▚▚▚▚█████████████                   1 3 0 0  0  archived/projects/tangerine.md
                                             ──────────
-                                            2 5 1 2 19  29, of 29 total
+                                            2 5 1 2 23  33, of 33 total
 
         ▚ Cancelled  █ Done  ▓ Blocked  ▒ Partial  ░ Open
         EOF
@@ -93,12 +95,13 @@ function setup {
                     C D B P  O
         ░░░░        0 0 0 0  3  tasks.md
         ░░░░░       0 0 0 0  4  projects/curtain.md
+        ░░░░░       0 0 0 0  4  projects/fountain.md
         ▚█▒▒░░░░░░  1 1 0 1  5  projects/harvest.md
         █▓▒▒░░      0 1 1 1  2  projects/obelisk.md
         ░░░░░░      0 0 0 0  5  projects/tinsel.md
         ▚████       1 3 0 0  0  archived/projects/tangerine.md
                     ──────────
-                    2 5 1 2 19  29, of 29 total
+                    2 5 1 2 23  33, of 33 total
 
         ▚ Cancelled  █ Done  ▓ Blocked  ▒ Partial  ░ Open
         EOF
@@ -115,14 +118,15 @@ function setup {
                 --open
 
     expected_output=$(sed -e 's/^        //' <<"        EOF"
-                                                                O
-        ████████████████████████████████                        3  tasks.md
-        ███████████                                             1  projects/curtain.md
-        █████████████████████████████████████████████████████   5  projects/harvest.md
-        █████████████████████                                   2  projects/obelisk.md
-        █████████████████████████████████████████████████████   5  projects/tinsel.md
-                                                               ──
-                                                               16  16, of 29 total
+                                                               O
+        ███████████████████████████████                        3  tasks.md
+        ██████████                                             1  projects/curtain.md
+        ██████████████████████████████████████████             4  projects/fountain.md
+        ████████████████████████████████████████████████████   5  projects/harvest.md
+        █████████████████████                                  2  projects/obelisk.md
+        ████████████████████████████████████████████████████   5  projects/tinsel.md
+                                                              ──
+                                                              20  20, of 33 total
 
         █ Open
         EOF
@@ -143,12 +147,13 @@ function setup {
                                                   O  ~
         ███████████████                           3  0  tasks.md
         █████                                     1  0  projects/curtain.md
+        ████████████████████                      4  0  projects/fountain.md
         ████████████████████████░░░░░░░░░░░░░░░   5  3  projects/harvest.md
         ██████████░░░░░░░░░░░░░░                  2  3  projects/obelisk.md
         ████████████████████████                  5  0  projects/tinsel.md
         ░░░░░░░░░░░░░░░░░░░░                      0  4  archived/projects/tangerine.md
                                                  ─────
-                                                 16 10  26, of 29 total
+                                                 20 10  30, of 33 total
 
         █ Open  ░ (Cancelled/Done/Blocked/Partial)
         EOF
@@ -169,12 +174,13 @@ function setup {
                                                   P  ~
         ░░░░░░░░░░░░░░░                           0  3  tasks.md
         ░░░░░                                     0  1  projects/curtain.md
+        ░░░░░░░░░░░░░░░░░░░░                      0  4  projects/fountain.md
         █████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  1  7  projects/harvest.md
         █████░░░░░░░░░░░░░░░░░░░░                 1  4  projects/obelisk.md
         ░░░░░░░░░░░░░░░░░░░░░░░░░                 0  5  projects/tinsel.md
         ░░░░░░░░░░░░░░░░░░░░                      0  4  archived/projects/tangerine.md
                                                   ────
-                                                  2 24  26, of 29 total
+                                                  2 28  30, of 33 total
 
         █ Partial  ░ (Cancelled/Done/Blocked/Open)
         EOF
@@ -195,12 +201,13 @@ function setup {
                                                   B  ~
         ░░░░░░░░░░░░░░░                           0  3  tasks.md
         ░░░░░                                     0  1  projects/curtain.md
+        ░░░░░░░░░░░░░░░░░░░░                      0  4  projects/fountain.md
         ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  0  8  projects/harvest.md
         █████░░░░░░░░░░░░░░░░░░░░                 1  4  projects/obelisk.md
         ░░░░░░░░░░░░░░░░░░░░░░░░░                 0  5  projects/tinsel.md
         ░░░░░░░░░░░░░░░░░░░░                      0  4  archived/projects/tangerine.md
                                                   ────
-                                                  1 25  26, of 29 total
+                                                  1 29  30, of 33 total
 
         █ Blocked  ░ (Cancelled/Done/Partial/Open)
         EOF
@@ -221,12 +228,13 @@ function setup {
                                                   D  ~
         ░░░░░░░░░░░░░░░                           0  3  tasks.md
         ░░░░░                                     0  1  projects/curtain.md
+        ░░░░░░░░░░░░░░░░░░░░                      0  4  projects/fountain.md
         █████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  1  7  projects/harvest.md
         █████░░░░░░░░░░░░░░░░░░░░                 1  4  projects/obelisk.md
         ░░░░░░░░░░░░░░░░░░░░░░░░░                 0  5  projects/tinsel.md
         ███████████████░░░░░                      3  1  archived/projects/tangerine.md
                                                   ────
-                                                  5 21  26, of 29 total
+                                                  5 25  30, of 33 total
 
         █ Done  ░ (Cancelled/Blocked/Partial/Open)
         EOF
@@ -247,12 +255,13 @@ function setup {
                                                   C  ~
         ░░░░░░░░░░░░░░░                           0  3  tasks.md
         ░░░░░                                     0  1  projects/curtain.md
+        ░░░░░░░░░░░░░░░░░░░░                      0  4  projects/fountain.md
         █████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  1  7  projects/harvest.md
         ░░░░░░░░░░░░░░░░░░░░░░░░░                 0  5  projects/obelisk.md
         ░░░░░░░░░░░░░░░░░░░░░░░░░                 0  5  projects/tinsel.md
         █████░░░░░░░░░░░░░░░                      1  3  archived/projects/tangerine.md
                                                   ────
-                                                  2 24  26, of 29 total
+                                                  2 28  30, of 33 total
 
         █ Cancelled  ░ (Done/Blocked/Partial/Open)
         EOF
@@ -274,12 +283,13 @@ function setup {
                                                 C  O ~
         ▓▓▓▓▓▓▓▓▓▓▓▓▓▓                          0  3 0  tasks.md
         ▓▓▓▓▓                                   0  1 0  projects/curtain.md
+        ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓                     0  4 0  projects/fountain.md
         ▚▚▚▚▚▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░  1  5 2  projects/harvest.md
         ▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░                0  2 3  projects/obelisk.md
         ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓                0  5 0  projects/tinsel.md
         ▚▚▚▚▚░░░░░░░░░░░░░░                     1  0 3  archived/projects/tangerine.md
                                                 ──────
-                                                2 16 8  26, of 29 total
+                                                2 20 8  30, of 33 total
 
         ▚ Cancelled  ▓ Open  ░ (Done/Blocked/Partial)
         EOF
@@ -300,12 +310,13 @@ function setup {
                                                   H  ~
         ░░░░░░░░░░░░░░░                           0  3  tasks.md
         ░░░░░                                     0  1  projects/curtain.md
+        ░░░░░░░░░░░░░░░░░░░░                      0  4  projects/fountain.md
         ███████████████░░░░░░░░░░░░░░░░░░░░░░░░░  3  5  projects/harvest.md
         ░░░░░░░░░░░░░░░░░░░░░░░░░                 0  5  projects/obelisk.md
         ░░░░░░░░░░░░░░░░░░░░░░░░░                 0  5  projects/tinsel.md
         ░░░░░░░░░░░░░░░░░░░░                      0  4  archived/projects/tangerine.md
                                                   ────
-                                                  3 23  26, of 29 total
+                                                  3 27  30, of 33 total
 
         █ High  ░ (Overdue/Imminent/Medium/Normal)
         EOF
@@ -326,12 +337,13 @@ function setup {
                                                   M  ~
         █████░░░░░░░░░░                           1  2  tasks.md
         ░░░░░                                     0  1  projects/curtain.md
+        ░░░░░░░░░░░░░░░░░░░░                      0  4  projects/fountain.md
         █████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  1  7  projects/harvest.md
         ░░░░░░░░░░░░░░░░░░░░░░░░░                 0  5  projects/obelisk.md
         ░░░░░░░░░░░░░░░░░░░░░░░░░                 0  5  projects/tinsel.md
         ░░░░░░░░░░░░░░░░░░░░                      0  4  archived/projects/tangerine.md
                                                   ────
-                                                  2 24  26, of 29 total
+                                                  2 28  30, of 33 total
 
         █ Medium  ░ (Overdue/Imminent/High/Normal)
         EOF
@@ -353,12 +365,13 @@ function setup {
                                                H  N  ~
         ▓▓▓▓▓▓▓▓▓░░░░░                         0  2  1  tasks.md
         ▓▓▓▓▓                                  0  1  0  projects/curtain.md
+        ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓                     0  4  0  projects/fountain.md
         ▚▚▚▚▚▚▚▚▚▚▚▚▚▚▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░  3  2  3  projects/harvest.md
         ▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░                0  3  2  projects/obelisk.md
         ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓                0  5  0  projects/tinsel.md
         ░░░░░░░░░░░░░░░░░░                     0  0  4  archived/projects/tangerine.md
                                                ───────
-                                               3 13 10  26, of 29 total
+                                               3 17 10  30, of 33 total
 
         ▚ High  ▓ Normal  ░ (Overdue/Imminent/Medium)
         EOF

{whatnext-2.0 → whatnext-2.1}/tests/test_file.py

@@ -876,3 +876,70 @@ class TestNotnextParsing:
             today=date(2025, 1, 1),
         )
         assert file.notnext is False
+
+
+class TestQueueParsing:
+    def test_file_without_queue(self):
+        file = MarkdownFile(
+            source_string="- [ ] normal task",
+            today=date(2025, 1, 1),
+        )
+        assert file.queue is False
+
+    def test_file_with_queue(self):
+        file = MarkdownFile(
+            source_string=dedent("""\
+                @queue
+
+                - [ ] first task
+                - [ ] second task
+            """),
+            today=date(2025, 1, 1),
+        )
+        assert file.queue is True
+
+    def test_queue_anywhere_in_file(self):
+        file = MarkdownFile(
+            source_string=dedent("""\
+                # Tasks
+
+                - [ ] first task
+
+                @queue
+            """),
+            today=date(2025, 1, 1),
+        )
+        assert file.queue is True
+
+    def test_escaped_queue_in_backticks(self):
+        file = MarkdownFile(
+            source_string=dedent("""\
+                Use `@queue` to limit output.
+
+                - [ ] first task
+            """),
+            today=date(2025, 1, 1),
+        )
+        assert file.queue is False
+
+    def test_escaped_queue_with_backslash(self):
+        file = MarkdownFile(
+            source_string=dedent("""\
+                Use \\@queue to limit output.
+
+                - [ ] first task
+            """),
+            today=date(2025, 1, 1),
+        )
+        assert file.queue is False
+
+    def test_queue_must_be_on_own_line(self):
+        file = MarkdownFile(
+            source_string=dedent("""\
+                # Tasks
+
+                - [ ] something @queue something else
+            """),
+            today=date(2025, 1, 1),
+        )
+        assert file.queue is False

{whatnext-2.0 → whatnext-2.1}/whatnext/guide.txt

@@ -46,6 +46,15 @@ subset. Prioritisation does not stop the task being ignored.
 To write about @after or deadlines without them being parsed, use backticks
 (`@after`) or a backslash (\@after).
 
+For sequential work where each task in the file can only be done after the
+previous tasks are complete, add @queue and output is limited to the next
+available most important task.
+
+    @queue
+    - [ ] backup production database
+    - [ ] run migration to add audit columns
+    - [ ] backfill audit data from logs
+
 Context around tasks, such as detailed decision notes and designs can be
 included in the document without showing in the task list. To include a
 short note in the summary, use special fence blocks:

{whatnext-2.0 → whatnext-2.1}/whatnext/models.py

@@ -102,6 +102,7 @@ class Task:
         self.deferred = deferred
 
     def as_dict(self):
+        # provided for easier testing
         return {
             "heading": self.heading,
             "state": self.state,
@@ -172,17 +173,27 @@ class Task:
         )
 
     def wrapped_heading(self, width=80, indent="    "):
-        if not self.heading:
-            return []
-        heading = self.heading
         if self.priority == Priority.OVERDUE:
-            heading = f"{self.heading} / OVERDUE {self.format_overdue_duration()}"
+            suffix = f"OVERDUE {self.format_overdue_duration()}"
         elif self.priority == Priority.IMMINENT:
-            heading = f"{self.heading} / IMMINENT {self.format_imminent_countdown()}"
+            suffix = f"IMMINENT {self.format_imminent_countdown()}"
         elif self.priority is None:
-            heading = f"{self.heading} / FINISHED"
+            suffix = "FINISHED"
         elif self.priority != Priority.NORMAL:
-            heading = f"{self.heading} / {self.priority.label.upper()}"
+            suffix = self.priority.label.upper()
+        else:
+            suffix = None
+
+        if self.heading:
+            if suffix:
+                heading = f"{self.heading} / {suffix}"
+            else:
+                heading = self.heading
+        elif suffix:
+            heading = f"# {suffix}"
+        else:
+            return []
+
         if width is None or len(indent + heading) <= width:
             return [indent + heading]
         return textwrap.wrap(
@@ -232,6 +243,7 @@ class MarkdownFile:
     """, re.VERBOSE)
     FILE_AFTER_PATTERN = re.compile(r"^@after(?:\s+(.+))?\s*$")
     NOTNEXT_PATTERN = re.compile(r"^@notnext(?:\s|$)")
+    QUEUE_PATTERN = re.compile(r"^@queue(?:\s|$)")
     DEFAULT_URGENCY = timedelta(weeks=2)
 
     def __init__(
@@ -259,6 +271,7 @@ class MarkdownFile:
         self.today = today
         self.warnings = []
         self.notnext = False
+        self.queue = False
         self.tasks = self.extract_tasks()
 
     @staticmethod
@@ -378,6 +391,8 @@ class MarkdownFile:
                 lines.append((line_index, line))
             elif self.NOTNEXT_PATTERN.match(line):
                 lines.append((line_index, line))
+            elif self.QUEUE_PATTERN.match(line):
+                lines.append((line_index, line))
 
         return lines
 
@@ -395,6 +410,8 @@ class MarkdownFile:
                     file_deferred = []
             if self.NOTNEXT_PATTERN.match(line):
                 self.notnext = True
+            if self.QUEUE_PATTERN.match(line):
+                self.queue = True
 
         heading = None
         priority = Priority.NORMAL

{whatnext-2.0 → whatnext-2.1}/whatnext/whatnext.py

@@ -135,6 +135,44 @@ def filter_deferred(data):
     return result
 
 
+def filter_queue(data):
+    result = []
+    for file, tasks in data:
+        if not file.queue:
+            result.append((file, tasks))
+            continue
+
+        in_progress = [
+            t for t in tasks
+                if t.state == State.IN_PROGRESS
+        ]
+        if in_progress:
+            result.append((file, in_progress))
+            continue
+
+        open_tasks = [
+            t for t in tasks
+                if t.state == State.OPEN
+        ]
+        if open_tasks:
+            best = min(open_tasks, key=lambda t: t.priority.value)
+            result.append((file, [best]))
+            continue
+
+        blocked = [
+            t for t in tasks
+                if t.state == State.BLOCKED
+        ]
+        if blocked:
+            best = min(blocked, key=lambda t: t.priority.value)
+            result.append((file, [best]))
+            continue
+
+        result.append((file, []))
+
+    return result
+
+
 def get_terminal_width():
     columns_env = os.environ.get("COLUMNS")
     if columns_env:
@@ -253,11 +291,14 @@ def flatten_by_priority(filtered_data):
     return result
 
 
+_NOT_YET_SHOWN = object()
+
+
 def format_tasks(tasks, width, use_colour=False):
     output = []
     current_priority = None
     current_file = None
-    current_heading = None
+    current_heading = _NOT_YET_SHOWN
 
     for task in tasks:
         if task.priority != current_priority:
@@ -265,7 +306,7 @@ def format_tasks(tasks, width, use_colour=False):
                 output.append("")
             current_priority = task.priority
             current_file = None
-            current_heading = None
+            current_heading = _NOT_YET_SHOWN
 
         text_colour = None
         block_colour = None
@@ -281,9 +322,9 @@ def format_tasks(tasks, width, use_colour=False):
         if task.file != current_file:
             lines.append(f"{task.file.display_path}:")
             current_file = task.file
-            current_heading = None
+            current_heading = _NOT_YET_SHOWN
 
-        if task.heading and task.heading != current_heading:
+        if task.heading != current_heading:
             lines.extend(task.wrapped_heading(width))
             current_heading = task.heading
             if task.annotation:
@@ -550,6 +591,9 @@ def main():
     if not args.all and not args.ignore_after:
         filtered_data = filter_deferred(filtered_data)
 
+    if not args.all and not args.summary:
+        filtered_data = filter_queue(filtered_data)
+
     if args.summary:
         output = format_summary(
             filtered_data,

whatnext-2.0/tests/headerless.md

@@ -1 +0,0 @@
-- [ ] I am not a task, I am a free list!