@basementuniverse/kanbn 2.0.0 → 2.5.0

package/docs/commands/find.txt

@@ -78,7 +78,7 @@ Options:
     The date can be in (almost) any format.
 
   {b}kanbn find --assigned "name"{b}
-    Find tasks assigned to a specific user. Use "^$" to find unassigned tasks.
+    Find tasks assigned to a specific user. Use "^$" to find unassigned tasks, and {b}@me{b} for tasks assigned to you.
 
   {b}kanbn find --workload N{b}
     Find tasks with a specific calculated workload.
@@ -88,6 +88,28 @@ Options:
     Find tasks with a specific progress value (between 0 and 1).
     If multiple values are specified, find tasks with progress between the lowest and highest inputs.
 
+  {b}kanbn find --overdue{b}
+  {b}kanbn find --no-overdue{b}
+    Find tasks that are (or are not) overdue. A task is overdue if it has a due date in the past and
+    hasn't been completed. A task with no due date is never overdue.
+
+  {b}kanbn find --is-started{b}
+  {b}kanbn find --no-is-started{b}
+    Find tasks that do (or don't) have a started date in their metadata.
+
+  {b}kanbn find --is-completed{b}
+  {b}kanbn find --no-is-completed{b}
+    Find tasks that do (or don't) have a completed date in their metadata.
+
+  {b}kanbn find --in-started-column{b}
+  {b}kanbn find --no-in-started-column{b}
+    Find tasks that are (or aren't) in one of the board's startedColumns. If the board declares no
+    startedColumns, no task is in a started column.
+
+  {b}kanbn find --in-completed-column{b}
+  {b}kanbn find --no-in-completed-column{b}
+    Find tasks that are (or aren't) in one of the board's completedColumns.
+
   {b}kanbn find --sub-task "search term"{b}
   {b}kanbn find -s "search term"{b}
     Find tasks that have sub-tasks matching the search term.
@@ -137,3 +159,19 @@ Examples:
 
   {b}kanbn find --count-sub-tasks 1 --count-sub-tasks 99 --progress 0 -q{b}
     List the ids of tasks that have sub-tasks but no progress yet.
+
+  {b}kanbn find --overdue --no-in-started-column -q{b}
+    List the ids of overdue tasks that nobody has picked up yet.
+
+  {b}kanbn find --board "board-slug"{b}
+  {b}kanbn find -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.
+
+  {b}kanbn find --all-boards{b}
+    Search every board in the workspace. A task on several boards appears once, annotated with the
+    board and column it occupies on each. Without this, the search is scoped to the target board.
+    Computed values are evaluated per board, so a task matches {b}--in-started-column{b} if it is in
+    a started column on any of them.
+    This can't be combined with {b}--sprint{b}: sprint numbers and names are relative to one board's
+    list, so there is no sensible answer across several.

package/docs/commands/gantt.txt

@@ -14,6 +14,7 @@ Options:
     Output raw data instead of rendering a chart. The data will be returned in JSON format.
 
   {b}kanbn gantt --assigned "user"{b}
+  {b}kanbn gantt --assigned @me{b}
   {b}kanbn gantt -a "user"{b}
     Filter for tasks that are assigned to a particular user.
 
@@ -30,3 +31,8 @@ Options:
   {b}kanbn gantt --now "date"{b}
   {b}kanbn gantt -n "date"{b}
     Mock the current date used for the "now" line and single-date range filtering.
+
+  {b}kanbn gantt --board "board-slug"{b}
+  {b}kanbn gantt -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/help.txt

@@ -7,6 +7,7 @@ Where {b}<command>{b} is one of:
   {b}version{b} {d}.......{d} Show package version
   {b}init{b} {d}..........{d} Initialise kanbn board
   {b}board{b} {d}.........{d} Show the kanbn board
+  {b}boards{b} {d}........{d} List the boards in this workspace
   {b}task{b} {d}..........{d} Show a kanbn task
   {b}add{b} {d}...........{d} Add a kanbn task
   {b}edit{b} {d}..........{d} Edit a kanbn task
@@ -25,6 +26,7 @@ Where {b}<command>{b} is one of:
   {b}restore{b} {d}.......{d} Restore a task from the archive
   {b}remove-all{b} {d}....{d} Remove the kanbn board and all tasks
   {b}history{b} {d}.......{d} Show task history
+  {b}contributors{b} {d}..{d} List the workspace's contributors
 
 For more help with commands, try:
 

package/docs/commands/history.txt

@@ -20,6 +20,7 @@ Options:
     If two or more dates are provided, show history from the earliest to latest date.
 
   {b}kanbn history --assigned "user"{b}
+  {b}kanbn history --assigned @me{b}
   {b}kanbn history -a "user"{b}
     Filter for tasks assigned to a specific user.
 
@@ -27,3 +28,8 @@ Options:
   {b}kanbn history -t "task-id"{b}
     Filter for one or more task ids.
     This option can be repeated.
+
+  {b}kanbn history --board "board-slug"{b}
+  {b}kanbn history -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/init.txt

@@ -19,3 +19,16 @@ Options:
   {b}kanbn init --column "column"{b}
   {b}kanbn init -c "column"{b}
     Initialise a kanbn board and add the specified column. This option can be repeated to add multiple columns.
+
+  {b}kanbn init --board "board-slug"{b}
+  {b}kanbn init -b "board-slug"{b}
+    Create a secondary board beside the main one, at {b}.kanbn/board-slug.md{b}. Secondary boards
+    share the main board's task folder, so a task can appear on several boards, in a different
+    column on each. Combine with {b}-n{b}, {b}-d{b} and {b}-c{b} to set the board's name,
+    description and columns:
+      {b}kanbn init -b design -n "Design Pipeline" -c Ideas -c Designing -c "Signed Off"{b}
+    Running it again on an existing board updates its name, description and columns, exactly as
+    {b}kanbn init{b} does for the main board. A new board only picks up the default started and
+    completed columns if it actually has columns by those names, so a board with its own workflow
+    doesn't silently inherit "In Progress" and "Done".
+    The workspace has to exist first - run {b}kanbn init{b} with no {b}-b{b} to create it.

package/docs/commands/move.txt

@@ -21,3 +21,29 @@ Options:
     Move the task to a position relative to its current position in the target column.
     When specifying a negative value for N, the negative sign can be escaped with '/' or '\\' to prevent the value being recognised as an option. For example:
     {b}kanbn mv "task-1" -p \\-1 --relative{b}
+
+  {b}kanbn move "task-id" --board "board-slug"{b}
+  {b}kanbn move "task-id" -b "board-slug"{b}
+    Move the task on a board other than the main one. If the task isn't on that board yet it is
+    added, with a notice - so pulling work onto a board is one command rather than two.
+
+  {b}kanbn move "task-id" -b "board-slug" --no-add{b}
+    Refuse to move a task that isn't on the target board, instead of adding it.
+    The main board never adds implicitly: moving an untracked task there is an error either way.
+
+
+Simple tasks - lines in a column that aren't task links - can be moved too, by title:
+
+  {b}kanbn move "Buy milk" -c "Done"{b}
+    Move a simple task to another column. The title matches exactly, ignoring case, or slugified.
+    A real task with the same id always wins. Leave off {b}-c{b} to reposition it in its own column.
+
+  {b}kanbn move "Buy milk" -b "board-slug" -c "column"{b}
+    Move a simple task onto another board. A simple task is content in one board file rather than a
+    shared task file, so this moves the line: it leaves this board and joins the other one.
+
+Boards can declare {b}actions{b} - rules that fire when a task changes, e.g. "when this enters In
+Progress, assign it to me and tag it active". See {b}docs/actions.md{b}.
+
+  {b}kanbn move --no-actions{b}
+    Run without firing any action rules. {b}KANBN_NO_ACTIONS=1{b} does the same for a whole shell.

package/docs/commands/remove.txt

@@ -1,12 +1,33 @@
 {b}kanbn remove "task-id"{b}
 {b}kanbn rm "task-id"{b}
 
-Remove an existing task.
+Remove an existing task. This deletes the task file and its index entry.
 
 Options:
   {b}kanbn remove "task-id" --index{b}
+  {b}kanbn remove "task-id" -x{b}
     Only remove the task from the index. The task file will not be deleted.
 
   {b}kanbn remove "task-id" --force{b}
   {b}kanbn remove "task-id" -f{b}
     Force remove the task without asking for confirmation.
+
+  {b}kanbn remove "task-id" --board "board-slug"{b}
+  {b}kanbn remove "task-id" -b "board-slug"{b}
+    Remove the task from that board. Combine this with {b}--index{b} to remove it from that board
+    only - boards own membership, so the task file and its entries on every other board are
+    untouched.
+
+  {b}kanbn remove "task-id" --all-boards{b}
+    Task files are shared between boards, so deleting one while another board still references it is
+    refused. This removes the task from every board that references it, then deletes the file.
+
+  {b}kanbn remove "Buy milk"{b}
+    Remove a simple task - a line in a column that isn't a task link - by title. There is no file to
+    delete and nothing to archive, so {b}--index{b} and {b}--all-boards{b} don't apply.
+
+Boards can declare {b}actions{b} - rules that fire when a task changes, e.g. "when this enters In
+Progress, assign it to me and tag it active". See {b}docs/actions.md{b}.
+
+  {b}kanbn remove --no-actions{b}
+    Run without firing any action rules. {b}KANBN_NO_ACTIONS=1{b} does the same for a whole shell.

package/docs/commands/rename.txt

@@ -11,3 +11,8 @@ Options:
   {b}kanbn rename "task-id" --name "name"{b}
   {b}kanbn rename "task-id" -n "name"{b}
     Rename the task with the specified name. This option is required if not renaming a task interactively.
+
+  {b}kanbn rename "task-id" --board "board-slug"{b}
+  {b}kanbn rename "task-id" -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/restore.txt

@@ -10,3 +10,15 @@ Options:
   {b}kanbn restore "task-id" --column "column"{b}
   {b}kanbn restore "task-id" -c "column"{b}
     Restore a task from the archive and place it in the specified column.
+
+  {b}kanbn restore "task-id" --board "board-slug"{b}
+  {b}kanbn restore "task-id" -b "board-slug"{b}
+    Restore the task to that board only. Without this, the task goes back to every board it was on
+    when it was archived, in the column it occupied on each. A board that has since been deleted is
+    reported and skipped rather than failing the restore.
+
+Boards can declare {b}actions{b} - rules that fire when a task changes, e.g. "when this enters In
+Progress, assign it to me and tag it active". See {b}docs/actions.md{b}.
+
+  {b}kanbn restore --no-actions{b}
+    Run without firing any action rules. {b}KANBN_NO_ACTIONS=1{b} does the same for a whole shell.

package/docs/commands/sort.txt

@@ -98,6 +98,21 @@ Options:
   {b}kanbn sort -w{b}
     Sort tasks by workload.
 
+  {b}kanbn sort --overdue{b}
+    Sort tasks by whether they are overdue. Ascending puts overdue tasks last.
+
+  {b}kanbn sort --is-started{b}
+    Sort tasks by whether they have a started date in their metadata.
+
+  {b}kanbn sort --is-completed{b}
+    Sort tasks by whether they have a completed date in their metadata.
+
+  {b}kanbn sort --in-started-column{b}
+    Sort tasks by whether they are in one of the board's startedColumns.
+
+  {b}kanbn sort --in-completed-column{b}
+    Sort tasks by whether they are in one of the board's completedColumns.
+
   {b}kanbn sort --<custom field name>{b}
     Sort tasks by a custom field value.
 
@@ -107,3 +122,11 @@ Examples:
 
   {b}kanbn sort "Todo" -z -n --count-tags{b}
     Sort tasks in the "Todo" column first by name, then by the number of tags, all in descending order
+
+  {b}kanbn sort "Todo" --overdue -z -e -a{b}
+    Sort tasks in the "Todo" column so that overdue tasks come first, then by due date in ascending order
+
+  {b}kanbn sort "column" --board "board-slug"{b}
+  {b}kanbn sort "column" -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/sprint.txt

@@ -15,3 +15,12 @@ Options:
   {b}kanbn sprint --description "description"{b}
   {b}kanbn sprint -d "description"{b}
     Start a new sprint with the specified description.
+
+  {b}kanbn sprint --board "board-slug"{b}
+  {b}kanbn sprint -b "board-slug"{b}
+    Add a sprint from the context of another board. Sprints are workspace-level by default, so this
+    appends to the workspace list and says so. A board that declares its own {b}sprints{b} in its
+    front matter gets the sprint appended there instead, auto-named {b}{Board name} Sprint {n}{b} so
+    that two boards' sprints can't be confused.
+    A board with its own list can't see the workspace sprints at all - that's the cost of forking,
+    and it's why forking is a deliberate front-matter edit rather than a flag.

package/docs/commands/status.txt

@@ -15,7 +15,11 @@ Options:
 
   {b}kanbn status --untracked{b}
   {b}kanbn status -u{b}
-    Show a list of untracked task filenames.
+    Show a list of untracked task filenames. "Untracked" is workspace-scoped: a task is tracked if
+    any board references it, so this lists task files that are on no board at all.
+    When other boards track tasks that the target board doesn't, they're listed separately under
+    {b}tasksOnOtherBoards{b}, with the column each one occupies - the "what could I pull onto this
+    board" list.
 
   {b}kanbn status --due{b}
   {b}kanbn status -e{b}
@@ -33,3 +37,8 @@ Options:
     This option can be repeated - if multiple dates are specified, show task workloads for tasks between the earliest and latest dates.
     The date can be in (almost) any format.
     This option will be ignored if the --quiet or --sprint options are set.
+
+  {b}kanbn status --board "board-slug"{b}
+  {b}kanbn status -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.

package/docs/commands/task.txt

@@ -7,3 +7,12 @@ Options:
   {b}kanbn task "task-id" --json{b}
   {b}kanbn task "task-id" -j{b}
     Show task information in JSON format.
+
+  {b}kanbn task "task-id" --board "board-slug"{b}
+  {b}kanbn task "task-id" -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.
+
+  {b}kanbn task "Buy milk"{b}
+    A simple task - a line in a column that isn't a task link - has no task file to show, so this
+    reports which column it's in and how to promote it.

package/docs/commands/validate.txt

@@ -5,6 +5,11 @@ Validate kanbn index file and all task files, and report any formatting errors.
 If the files are valid, this also reports tasks whose started/completed dates don't match the column
 they're in - which usually means the task was moved by hand or by a merge, rather than through kanbn.
 
+It also lists any line in a column that isn't a task link. Those lines are kept in the board file and
+ignored by every other command, so this is information rather than a problem - except for a line that
+looks like a task link with a typo in it, or one naming a task file that exists, both of which mean a
+task isn't being tracked when it probably should be.
+
 Options:
   {b}kanbn validate --save{b}
     Re-save the index and task files. This will ensure that all index column sorting settings are applied and that all tasks are formatted correctly.
@@ -20,4 +25,27 @@ Options:
 
   {b}kanbn validate --json{b}
   {b}kanbn validate -j{b}
-    Output validation errors in JSON format.
+    Output validation errors in JSON format. When there is nothing to report beyond date drift this
+    is the bare list of drift entries; when there are warnings as well - or the workspace has more
+    than one board - it is an object with {b}drift{b} and {b}warnings{b} keys.
+
+  {b}kanbn validate --board "board-slug"{b}
+  {b}kanbn validate -b "board-slug"{b}
+    Target a board other than the main one. Falls back to the KANBN_BOARD environment variable and
+    then to the defaultBoard option. See {b}kanbn boards{b} for the list of boards.
+
+  {b}kanbn validate --all-boards{b}
+    Validate every board in the workspace and the tasks each of them references, rather than just
+    the target board.
+
+In a workspace with more than one board, {b}validate{b} also reports multi-board warnings - a
+workspace-scoped option in a board file, several boards stamping the same shared date, sprints out
+of order, a task on no board at all, history naming a board that has been deleted, and markdown
+files beside the boards that don't parse as one. These are warnings, not errors: each describes a
+workspace that still works, just not the way its author probably meant it to.
+
+Action rules are checked too. A rule that names an unknown event or verb, moves to a column that
+doesn't exist, or writes a field Kanbn manages is an {b}error{b} - the same commands that would have
+run it fail before writing anything. Rules that work but probably don't do what they look like -
+two rules writing the same field on the same event, or {b}@me{b} where no user can be resolved - are
+reported as warnings.

package/docs/contributors.md

@@ -0,0 +1,145 @@
+# Contributors
+
+`assigned` and comment `author` are free text, and they always will be. There is no authentication in
+Kanbn and there is never going to be any, so it cannot and should not try to prove that a given string
+corresponds to a given human — anyone who can edit `.kanbn/tasks/*.md` can write any name they like
+into any field.
+
+What Kanbn _can_ do is make the common case — "that's me" — a single keystroke instead of a retyped
+name, and make the set of names a workspace uses discoverable rather than folkloric. That is what
+`contributors` is for.
+
+**Contributors are a convenience list, not an access control list.** Nothing is validated against
+them, nothing is rejected, and nothing in an existing workspace changes when you add them.
+
+## Declaring contributors
+
+`contributors` is a [workspace-scoped option](index-structure.md#project-options): it goes in
+`kanbn.yml` / `kanbn.json`, or in the main board's front matter when there is no configuration file,
+and every board in the workspace inherits it. A secondary board that declares its own is reported by
+`kanbn validate` and ignored — a name written into a shared task file has to mean the same thing on
+every board that references that file.
+
+The shorthand is a bare name, which is all most workspaces ever need:
+
+```yaml
+contributors:
+  - gordon
+  - dave
+  - sam
+```
+
+The long form is for a contributor who needs more than a name. Both forms can appear in the same list:
+
+```yaml
+contributors:
+  - name: gordon
+    displayName: Gordon Larrigan
+    email: gordonlarrigan@example.com
+    aliases:
+      - Gordon Larrigan
+      - gordonl
+    colour: '#7c5cff'
+  - dave
+```
+
+| Field | Required | Purpose |
+| --- | --- | --- |
+| `name` | yes | The canonical value written into `assigned` and comment `author`. Everything else is lookup metadata |
+| `displayName` | no | Shown in UIs; never stored in a task file. Defaults to `name` |
+| `email` | no | Matched against `git config user.email` |
+| `aliases` | no | Other spellings that mean this person |
+| `colour` | no | Presentational only, for avatar chips. Kanbn stores and serves it, and never interprets it |
+
+`aliases` is the field that does the actual work. Without it, `contributors` is a list of strings a UI
+can put in a dropdown; with it, Kanbn can tell that the person at this machine is `gordon` even though
+git says `Gordon Larrigan`.
+
+## The current user
+
+Kanbn resolves a single answer to "who is the current user?", used by the CLI, the library and the
+VSCode extension. In order, first match wins:
+
+1. the `KANBN_USER` environment variable, used **exactly as given**
+2. `git config user.email` matched against a contributor's `email` → that contributor's `name`
+3. `git config user.name` matched against a contributor's `name`, `displayName` or `aliases`,
+   ignoring case → that contributor's `name`
+4. `git config user.name` as-is
+5. nobody
+
+Two things follow from that order:
+
+- **It degrades to what Kanbn has always done.** With no contributors declared, steps 2 and 3 can't
+  match and step 4 returns exactly the git username Kanbn used before this feature existed. A
+  workspace that ignores contributors sees no change at all.
+- **It canonicalises.** With contributors declared, a machine whose git username is `Gordon Larrigan`
+  writes `gordon` into the task file, because that is what the workspace has agreed to call him. That
+  is the typo mitigation, and it happens without anyone typing anything.
+
+`KANBN_USER` is used verbatim rather than canonicalised: it is the explicit override, for a machine
+whose git identity is wrong or missing, and an explicit value should be written exactly as given.
+
+Ask Kanbn who it thinks you are with `kanbn contributors`.
+
+_There is deliberately no `me` key in the config file. A `me` committed into a shared board file would
+tell every collaborator that they are you. `KANBN_USER` plus git resolution covers the real cases._
+
+## What uses it
+
+| Where | Behaviour |
+| --- | --- |
+| `kanbn add --assigned` (no value) | Assigns the task to the current user, canonicalised |
+| `kanbn edit "task-id" --assigned` (no value) | The same |
+| `kanbn comment "task-id"` | The comment author defaults to the current user, or to no author at all if there isn't one |
+| `kanbn add -i` / `kanbn edit -i` | "Assigned to:" becomes an autocomplete over the contributor list when one is declared. Free text is still accepted |
+| `kanbn find --assigned @me` | `@me` expands to the current user. Also `kanbn burndown`, `kanbn gantt` and `kanbn history` |
+| Task history | Each history event records the current user as its `author`, and no `author` key at all when there is no resolvable user |
+
+`@me` is only ever interpreted in a **filter** argument, never when setting a value and never inside a
+task file. If the current user can't be resolved, `@me` is an error rather than a filter that quietly
+matches everything.
+
+## Adopting contributors in an existing workspace
+
+`kanbn contributors --usage` shows how each contributor is actually used, and — the useful part —
+every name used in a task that isn't a known contributor:
+
+```
+$ kanbn contributors --usage
+2 contributors:
+
+gordon (you)
+  14 tasks, assigned 12, 4 comments
+  written as "Gordon Larrigan" in 2 tasks
+
+dave
+  6 tasks, assigned 6, 1 comment
+
+1 name is used in tasks but isn't a known contributor:
+
+Gordon
+  12 tasks, assigned 12, 0 comments
+  task-1, task-4, task-9, ...
+```
+
+That is the list of aliases to add. It is read-only: nothing is rewritten, because renaming `Gordon`
+to `gordon` across every task file is a bulk mutation that deserves its own command and its own dry
+run.
+
+`kanbn validate` reports the same thing more briefly, as a **warning** rather than an error — the
+tasks it names are working exactly as they always have. Nothing is reported at all when a workspace
+declares no contributors.
+
+## Deliberate omissions
+
+- **Validation.** `assigned` is never restricted to the contributor list. "If contributors is set,
+  only allow those values" turns an optional convenience into something that breaks a workspace
+  whenever someone adds a task on a machine with a stale config, or renames themselves, or receives a
+  task file from outside.
+- **Multiple assignees.** `assigned` is a single string in the schema, the filters, the board template
+  and three reporting commands. One assignee per task.
+- **Importing from `package.json`, `.mailmap` or `CODEOWNERS`.** npm contributors are publishers,
+  `.mailmap` is git plumbing, and `CODEOWNERS` is a permissions file — three different sets of
+  semantics, none of them this one.
+- **Anything resembling accounts.** No permissions, no ownership, no invites. If `contributors` ever
+  grows those, it has become an auth system by accident.

package/docs/filtering-and-sorting.md

@@ -41,7 +41,7 @@ filters:
 | `due` | `--due`, `-e` | date | `due` metadata |
 | `plannedStart` | `--plannedStart` | date | `plannedStart` metadata |
 | `plannedFinish` | `--plannedFinish` | date | `plannedFinish` metadata |
-| `assigned` | `--assigned` | string | `assigned` metadata (empty string if unset) |
+| `assigned` | `--assigned` | string | `assigned` metadata (empty string if unset). `@me` on the command line expands to the [current user](contributors.md#the-current-user) |
 | `workload` | `--workload` | number | The task's [calculated workload](index-structure.md#taskworkloadtags) |
 | `progress` | `--progress` | number | The task's [calculated progress](task-structure.md#progress) |
 | `sub-task` | `--sub-task`, `-s` | string | All sub-tasks, one per line, as `[ ] text` or `[x] text` |
@@ -52,6 +52,11 @@ filters:
 | `count-relations` | `--count-relations` | number | Number of relations |
 | `comment` | `--comment` | string | All comments, one per line, as `author text` |
 | `count-comments` | `--count-comments` | number | Number of comments |
+| `overdue` | `--overdue` | boolean | Whether the task is [overdue](#computed-values) |
+| `is-started` | `--is-started` | boolean | Whether the task has a started date |
+| `is-completed` | `--is-completed` | boolean | Whether the task has a completed date |
+| `in-started-column` | `--in-started-column` | boolean | Whether the task is in one of the board's `startedColumns` |
+| `in-completed-column` | `--in-completed-column` | boolean | Whether the task is in one of the board's `completedColumns` |
 | *custom field name* | `--<custom field name>` | declared type | The custom field value in the task metadata |
 
 Custom fields must be declared in the [`customFields`](index-structure.md#customfields) project option before they can be filtered on.
@@ -60,6 +65,8 @@ A task that doesn't have the metadata field being filtered on never matches a da
 
 *Note: `hiddenColumns` only affects the board. `kanbn find` still returns tasks in hidden columns unless you filter them out with `column`.*
 
+`@me` is substituted where the argument is parsed, so it works for `kanbn find --assigned @me` and for the simpler `--assigned` options on `kanbn burndown`, `kanbn gantt` and `kanbn history`. It is never interpreted when *setting* a value, and never inside a task file. If Kanbn can't work out who you are, `@me` is an error rather than a filter that quietly matches everything.
+
 ### String filters
 
 String filter values are **case-insensitive regular expressions**, matched anywhere in the value (not anchored). Passing an array (or repeating a CLI option) joins the values with `|`, so an array means "match any of these":
@@ -119,13 +126,53 @@ kanbn find --workload 3 --workload 8 # between 3 and 8
 
 ### Boolean filters
 
-Boolean filters only apply to custom fields with type `boolean`, and are matched by exact equality. On the command line, `--<name>` matches `true` and `--no-<name>` matches `false`:
+Boolean filters apply to the [computed values](#computed-values) and to custom fields with type `boolean`, and are matched by exact equality. On the command line, `--<name>` matches `true` and `--no-<name>` matches `false`:
 
 ```bash
 kanbn find --needsDesign     # tasks where needsDesign is true
 kanbn find --no-needsDesign  # tasks where needsDesign is false
+kanbn find --overdue         # overdue tasks
+kanbn find --no-overdue      # tasks that aren't overdue
 ```
 
+Leaving the option off entirely is different from passing `--no-<name>`: it means "don't filter on this at all".
+
+## Computed values
+
+Most filter and sorter fields read a value straight off the task. These five are worked out from the task *and* the board it is being filtered on, which makes them useful for questions the raw metadata can't answer on its own — "what is overdue and nobody has picked up", "what is sitting in a done column without a completed date".
+
+| Value | Meaning |
+| --- | --- |
+| `overdue` | The task has a `due` date that has passed **and** hasn't been completed. A task with no due date is never overdue, and neither is a completed task, however late it was. |
+| `is-started` | The task has a started date in its metadata. |
+| `is-completed` | The task has a completed date in its metadata. |
+| `in-started-column` | The task is currently in one of the board's [`startedColumns`](index-structure.md#startedcolumns). |
+| `in-completed-column` | The task is currently in one of the board's [`completedColumns`](index-structure.md#completedcolumns). |
+
+`is-started` and `is-completed` read the metadata fields the board is configured to use, so a board with a [`startedField`](index-structure.md#startedfield) or [`completedField`](index-structure.md#completedfield) override reports its own state rather than the built-in `started` / `completed` fields. A board that declares no `startedColumns` has no notion of work in progress, so nothing is in a started column; the same goes for `completedColumns`.
+
+`is-completed` and `in-completed-column` normally agree, because moving a task into a completed column is what stamps the completed date (likewise `is-started` and `in-started-column`). They come apart when a task is edited directly, when a board overrides the state fields, or when a task is moved back out of a column - which is exactly when it's worth asking about them separately:
+
+```bash
+# Tasks sitting in a completed column with no completed date
+kanbn find --in-completed-column --no-is-completed
+
+# Overdue work that nobody has picked up
+kanbn find --overdue --no-in-started-column
+```
+
+Under `kanbn find --all-boards` every board is filtered on its own, so a task matches `--in-started-column` if it is in a started column on **any** board in the workspace. Scope the question to one board with `--board`.
+
+As with the other fields, the name written in YAML is not always the command line option, and the sorter form is camelCase where the filter form is kebab-case:
+
+| Computed value | Filter field | Sorter field | CLI option |
+| --- | --- | --- | --- |
+| Overdue | `overdue` | `overdue` | `--overdue` |
+| Started | `is-started` | `isStarted` | `--is-started` |
+| Completed | `is-completed` | `isCompleted` | `--is-completed` |
+| In a started column | `in-started-column` | `inStartedColumn` | `--in-started-column` |
+| In a completed column | `in-completed-column` | `inCompletedColumn` | `--in-completed-column` |
+
 ## Sorters
 
 A sorter list is an ordered array. Tasks are compared using the first sorter; ties are broken using the next one, and so on. Each sorter is an object:
@@ -145,7 +192,12 @@ sorters:
 | `order` | no | `ascending` (default) or `descending` |
 | `filter` | no | A regex used to transform values before comparing them (see below) |
 
-Strings are compared with `localeCompare` (accent-sensitive, case-insensitive); dates and numbers are compared numerically.
+Strings are compared with `localeCompare` (accent-sensitive, case-insensitive); dates and numbers are compared numerically. Booleans sort `false` before `true`, so `order: descending` on a [computed value](#computed-values) brings the matching tasks to the top:
+
+```bash
+# Overdue tasks first, then everything else by due date
+kanbn sort "Todo" --overdue -z --due -a
+```
 
 ### Sort filters
 
@@ -188,6 +240,11 @@ kanbn sort "Todo" --name "Task (\d+)"
 | `countRelations` | `--count-relations` |
 | `comments` | `--comment` |
 | `countComments` | `--count-comments` |
+| `overdue` | `--overdue` |
+| `isStarted` | `--is-started` |
+| `isCompleted` | `--is-completed` |
+| `inStartedColumn` | `--in-started-column` |
+| `inCompletedColumn` | `--in-completed-column` |
 | *custom field name* | `--<custom field name>` |
 
 [View](views.md) column `sorters` accept all of the same fields, plus `column` (the index column the task is currently in), which is useful in a view whose columns don't map onto index columns.