@basementuniverse/kanbn 1.1.0 → 2.0.0

package/docs/filtering-and-sorting.md

@@ -0,0 +1,218 @@
+# Filtering and Sorting
+
+Kanbn uses one shared filtering model and one shared sorting model. They are used by:
+
+| Feature | Filters | Sorters |
+| --- | --- | --- |
+| `kanbn find` | yes (CLI options) | no |
+| `kanbn sort` | no | yes (CLI options) |
+| `columnSorting` project option | no | yes |
+| [Views](views.md) (root, column and lane filters) | yes | yes (per view column) |
+
+`kanbn status`, `kanbn burndown`, `kanbn gantt` and `kanbn history` have their own simpler `--column` / `--assigned` / `--date` / `--sprint` options and don't use this model.
+
+## Filters
+
+A filter set is a map of field names to filter values. **A task must match every filter in the set** (filters are combined with AND). An empty filter set matches all tasks.
+
+On the command line each `kanbn find` option is one filter. In the index options a filter set is a YAML object:
+
+```yaml
+filters:
+  column: 'In Progress'
+  tag: Bug
+  workload:
+    - 3
+    - 8
+```
+
+### Filter fields
+
+| Field | `kanbn find` option | Type | Matched against |
+| --- | --- | --- | --- |
+| `id` | `--id` | string | The task id (the task filename without `.md`) |
+| `name` | `--name`, `-n` | string | The task name (level-1 heading) |
+| `description` | `--description`, `-d` | string | The task description |
+| `column` | `--column`, `-c` | string | The name of the column the task is currently in |
+| `created` | `--created` | date | `created` metadata |
+| `updated` | `--updated` | date | `updated` metadata |
+| `started` | `--started` | date | `started` metadata |
+| `completed` | `--completed` | date | `completed` metadata |
+| `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) |
+| `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` |
+| `count-sub-tasks` | `--count-sub-tasks` | number | Number of sub-tasks |
+| `tag` | `--tag`, `-t` | string | All tags, one per line |
+| `count-tags` | `--count-tags` | number | Number of tags |
+| `relation` | `--relation`, `-r` | string | All relations, one per line, as `type task-id` |
+| `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 |
+| *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.
+
+A task that doesn't have the metadata field being filtered on never matches a date filter or a custom field filter. Missing `assigned` is treated as an empty string, missing `tags`/sub-tasks/relations/comments are treated as empty.
+
+*Note: `hiddenColumns` only affects the board. `kanbn find` still returns tasks in hidden columns unless you filter them out with `column`.*
+
+### 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":
+
+```bash
+kanbn find --column Todo --column "In Progress"
+```
+
+```yaml
+filters:
+  column:
+    - Todo
+    - 'In Progress'
+```
+
+Multi-value fields (`tag`, `sub-task`, `relation`, `comment`) are flattened into a single newline-separated string before matching. The regex is **not** built with the multiline flag, so `^` and `$` anchor to the start and end of that whole string, not to each line. To match a single value exactly, anchor on the line breaks instead:
+
+```bash
+# Matches "Bug", but also "Debug" and "Bugfix"
+kanbn find --tag Bug
+
+# Matches only the exact tag "Bug"
+kanbn find --tag '(^|\n)Bug($|\n)'
+```
+
+### Date filters
+
+A single date matches any task whose date falls on **the same calendar day** — the time part is ignored:
+
+```bash
+kanbn find --due "20 July 2026"
+```
+
+Two or more dates match any task whose date falls **between the earliest and latest** of them (inclusive, times included):
+
+```bash
+kanbn find --due "1 July 2026" --due "31 July 2026"
+```
+
+On the command line dates are parsed with [chrono](https://github.com/wanasit/chrono), so almost any format works, including relative dates like `"yesterday"` or `"next friday"`. In YAML, write dates as plain YAML timestamps:
+
+```yaml
+filters:
+  due:
+    - 2026-07-01
+    - 2026-07-31
+```
+
+### Number filters
+
+A single number matches that number exactly. Two or more numbers match anything between the lowest and highest (inclusive):
+
+```bash
+kanbn find --workload 5              # exactly 5
+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`:
+
+```bash
+kanbn find --needsDesign     # tasks where needsDesign is true
+kanbn find --no-needsDesign  # tasks where needsDesign is false
+```
+
+## 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:
+
+```yaml
+sorters:
+  - field: workload
+    order: descending
+  - field: name
+    filter: ''
+    order: ascending
+```
+
+| Property | Required | Description |
+| --- | --- | --- |
+| `field` | yes | The task field to sort by |
+| `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.
+
+### Sort filters
+
+The `filter` property is **not** a search filter — it extracts part of each value before comparing. The regex is applied globally and case-insensitively, and:
+
+- if it has named capturing groups, the contents of all named groups are concatenated;
+- otherwise, if it has numbered capturing groups, the contents of the first group are used;
+- otherwise, the whole match is used;
+- if there are multiple matches, their results are concatenated.
+
+```bash
+# Sort by the number in task names like "Task 12", not by the whole name
+kanbn sort "Todo" --name "Task (\d+)"
+```
+
+### Sortable fields
+
+`kanbn sort` and `columnSorting` can sort by any of these. Note that the `field` value written in YAML is **not** always the same as the command line option:
+
+| `field` value | `kanbn sort` option |
+| --- | --- |
+| `id` | `--id` |
+| `name` | `--name`, `-n` |
+| `description` | `--description`, `-d` |
+| `created` | `--created` |
+| `updated` | `--updated` |
+| `started` | `--started` |
+| `completed` | `--completed` |
+| `due` | `--due`, `-e` |
+| `plannedStart` | `--plannedStart` |
+| `plannedFinish` | `--plannedFinish` |
+| `assigned` | `--assigned` |
+| `workload` | `--workload`, `-w` |
+| `progress` | `--progress` |
+| `subTasks` | `--sub-task`, `-s` |
+| `countSubTasks` | `--count-sub-tasks` |
+| `tags` | `--tag`, `-t` |
+| `countTags` | `--count-tags` |
+| `relations` | `--relation`, `-r` |
+| `countRelations` | `--count-relations` |
+| `comments` | `--comment` |
+| `countComments` | `--count-comments` |
+| *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.
+
+A view sorter only changes the order within that view. To order a column permanently, use `columnSorting` — that ordering is written to the index itself, and view columns with no `sorters` of their own inherit it.
+
+## Persistent column sorting
+
+`columnSorting` keeps a column sorted in the index file itself, so the order survives `kanbn add`, `kanbn move` and `kanbn validate --save`:
+
+```yaml
+columnSorting:
+  Backlog:
+    - field: workload
+      order: descending
+    - field: name
+      order: ascending
+```
+
+You can also write this from the command line:
+
+```bash
+kanbn sort "Backlog" --workload -z --name -a --save
+```
+
+Running `kanbn sort "Backlog"` **without** `--save` removes any saved sorting settings for that column after applying the sort once.
+
+See `kanbn find --help` and `kanbn sort --help` for the full list of command line options, and [Views](views.md) for filters and sorters inside board views.

package/docs/index-structure.md

@@ -67,23 +67,23 @@ taskTemplate: ""
 dateFormat: ""
 views:
   - name: My view 1
+    filters:
+      tag: Bug
     columns:
-      "Column 1":
-        - hidden: false
-          filters:
-            name: /test/
-            workload:
-              - 1
-              - 5
-          sorters:
-            - field: name
-              filter: ""
-              order: ascending
-    lanes:
-      - name: "Lane 1"
-        filter:
+      - name: Column 1
+        filters:
+          name: test
+          workload:
+            - 1
+            - 5
+        sorters:
           - field: name
             filter: ""
+            order: ascending
+    lanes:
+      - name: Lane 1
+        filters:
+          assigned: username
 customFields:
   - name: 'myCustomField'
     type: 'date'
@@ -95,13 +95,40 @@ customFields:
 
 A list of column names. These columns will be hidden from the kanbn board.
 
+This only affects the default board layout. Tasks in hidden columns are still tracked, still show up in `kanbn find` and `kanbn status`, and are still shown by any [view](views.md) that defines its own `columns`.
+
 ### `startedColumns`
 
 A list of column names. When a task is created in or dragged into one of these columns, the task's `started` date will be set to the current time, unless the task already has a 'started' date.
 
 ### `completedColumns`
 
-A list of column names. When a task is created in or dragged into one of these columns, the task's `completed` date will be set to the current time. If the task already has a `completed` date, this date will be updated.
+A list of column names. When a task is created in or dragged into one of these columns, the task's `completed` date will be set to the current time, unless the task already has a `completed` date.
+
+Note that these columns control when the date is *written*. They don't decide whether a task counts as complete - that comes from the date itself. See [Task state](#task-state) below.
+
+### `startedField`
+
+The name of the metadata field that holds a task's started date. Defaults to `started`.
+
+### `completedField`
+
+The name of the metadata field that holds a task's completed date. Defaults to `completed`.
+
+Pointing these at custom date fields lets a board track its own started/completed state without touching the shared `started` and `completed` fields:
+
+```yaml
+completedField: designSignedOffAt
+completedColumns:
+  - Signed Off
+customFields:
+  - name: designSignedOffAt
+    type: date
+```
+
+### `verbose`
+
+Set to `false` to suppress hints and notices printed alongside normal output, such as the reminder shown when tasks have dates that don't match their column. Defaults to `true`. Hints are never shown when using `--json`.
 
 ### `sprints`
 
@@ -123,7 +150,9 @@ An associative array of column names and sorters. Each column can have an array
 
 The `filter` property can be used to transform values before sorting.
 
-Run `kanbn sort --help` for more information.
+Columns listed here are re-sorted every time Kanbn writes the index, so the order survives `kanbn add`, `kanbn move` and `kanbn validate --save`.
+
+See [Filtering and Sorting](filtering-and-sorting.md#sorters), or run `kanbn sort --help`.
 
 ### `taskTemplate`
 
@@ -137,6 +166,7 @@ updated
 started
 completed
 due
+assigned
 tags
 subTasks
 relations
@@ -149,6 +179,8 @@ progress
 {...customFields}
 ```
 
+*Note: referencing a variable that isn't in the list above (or a custom field that isn't declared in `customFields`) will print "Unable to build task template" instead of rendering the board.*
+
 The default task template is `^+^_${overdue ? '^R' : ''}${name}^: ${created ? ('\\n^-^/' + created) : ''}`.
 
 This string can contain markup sequences. See [terminal-kit](https://github.com/cronvel/terminal-kit/blob/21607fb51749853dd9193c6aaf205b14c63b2768/doc/markup.md#markup) for markup reference.
@@ -161,11 +193,13 @@ The date format to use for dates on the kanbn board and burndown chart views. Se
 
 ### `views`
 
-An array of views that can be used to customize how the kanbn board is displayed.
+An array of views that can be used to customize how the kanbn board is displayed. Select a view with `kanbn board --view "name"`.
+
+Each view has a required `name`, an optional root `filters` object, an optional array of `columns` and an optional array of `lanes`. Each column has a required `name` and optional `filters` and `sorters`. Each lane has a required `name` and optional `filters`.
 
-Each view should have a `name` property (run `kanbn board --view "name"` to specify which view to use), a list of columns and a list of lanes.
+If `columns` is omitted, the index columns are used (minus `hiddenColumns`). If `lanes` is omitted, a single lane containing all matching tasks is used.
 
-Each column can be hidden, filtered or sorted. Each lane has a list of filters.
+See [Views](views.md) for a full description and worked examples, and [Filtering and Sorting](filtering-and-sorting.md) for the filter and sorter formats.
 
 ### `customFields`
 
@@ -204,3 +238,18 @@ Here's an example of how this could be used:
     - Testing
   ```
 * When a task is moved into the `Testing` column and the task doesn't already have a `testedAt` value in its metadata, this value will be automatically populated with the current date/time.
+
+## Task state
+
+Whether a task has started or been completed is decided by its metadata dates, and nothing else:
+
+* a task has started if its `started` field is set (or whichever field `startedField` names);
+* a task is complete if its `completed` field is set (or whichever field `completedField` names).
+
+The column a task sits in doesn't make it started or complete. Columns listed in `startedColumns` and `completedColumns` cause those dates to be *written* when a task is moved through the CLI or the VSCode extension, but the dates are what everything else reads: `kanbn status`, `kanbn find`, progress, burndown charts and gantt charts.
+
+This matters when a task is moved **outside** of kanbn - by editing the index file by hand, or through a git merge. No date is written in that case, so the task keeps whatever state its metadata already described. `kanbn validate` reports tasks whose dates and columns disagree, and `kanbn validate --fix` fills in the missing dates, taking them from the task's history where possible.
+
+To clear a date - for example to reopen a task that was completed - use `kanbn edit "task-id" --unset completed`.
+
+_Note: before version 2.0.0, a task sitting in a completed column counted as complete even with no `completed` date. See [Migrating to 2.0.0](migration-2.0.md)._

package/docs/index.md

@@ -7,6 +7,30 @@ To get started quickly, check out the [Quick Start](quick-start.md) guide.
 ## Contents
 
 - [Quick Start](quick-start.md)
-- [Index Structure](index-structure.md)
-- [Task Structure](task-structure.md)
+- [Index Structure](index-structure.md) — the board file and all project options
+- [Task Structure](task-structure.md) — task files, metadata, sub-tasks, relations, comments and history
+- [Views](views.md) — custom board layouts, columns and lanes
+- [Filtering and Sorting](filtering-and-sorting.md) — the filter and sorter model shared by `find`, `sort` and views
 - [Advanced Configuration](advanced-configuration.md)
+- [Migrating to 2.0.0](migration-2.0.md) — separate config files and custom folder locations
+
+## Examples
+
+The [`example`](../example) directory contains ready-to-run boards:
+
+| Example | Demonstrates |
+| --- | --- |
+| [`example/basic`](../example/basic) | A typical board: columns, tags, workload, sprints |
+| [`example/views`](../example/views) | Views, lanes, filters and sorters |
+| [`example/advanced`](../example/advanced) | A `kanbn.yml` config file, custom fields, column sorting and a custom task template |
+
+Run any Kanbn command from inside one of those directories to try it out.
+
+## Command help
+
+Every command has built-in help:
+
+```bash
+kanbn help <command>
+kanbn <command> --help
+```

package/docs/migration-2.0.md

@@ -0,0 +1,92 @@
+# Migrating to 2.0.0
+
+Version 2.0.0 changes how kanbn decides whether a task has started or been completed. Everything else about the file format is unchanged: your `index.md` and task files are read and written exactly as before, and no migration step is required to open an existing board.
+
+## What changed
+
+**Before**, a task counted as complete if *either* it had a `completed` date *or* it was sitting in a column listed in `completedColumns`. The same applied to `started` and `startedColumns` when drawing burndown charts.
+
+**Now**, only the dates count. A task has started if its `started` date is set, and it is complete if its `completed` date is set.
+
+Columns still cause those dates to be written. Moving a task into a completed column through `kanbn move`, `kanbn edit -c`, or the VSCode extension sets its `completed` date exactly as it did before. What's changed is that the column no longer *stands in for* the date.
+
+## Why
+
+Inferring state from columns produced results that contradicted themselves and couldn't be corrected:
+
+* `kanbn status --due` could report a task as `completed: true` with `completedDate: null` - complete, but with no record of when.
+* Burndown charts substituted a task's **created** date when it had no started date, inventing timings unrelated to when the work happened.
+* State could only ever move forwards. Once a `completed` date was written, moving the task back out of the column didn't clear it, and there was no command that could.
+* A task could be complete on one board and not another purely because of what its columns were called - which becomes a real problem now that a task can appear on several boards.
+
+## What you might notice
+
+* **Tasks moved by hand.** If you moved a task between columns by editing `index.md` directly, or a git merge moved it, no date was written. Those tasks will now show as not started or not complete.
+* **Burndown charts will look different** for any board where dates and columns disagreed.
+* **Generated boards.** Tasks written by a tool or an AI assistant may sit in `Done` without a `completed` date.
+
+Boards that have only ever been driven through the CLI or the VSCode extension already have the right dates and won't change.
+
+## Fixing up an existing board
+
+```
+kanbn validate
+```
+
+reports every task whose dates and column disagree, in both directions:
+
+```
+2 tasks have dates that don't match their column:
+  bravo: task is in column "In Progress" but has no started date
+  alpha: task is in column "Done" but has no completed date
+```
+
+```
+kanbn validate --fix
+```
+
+fills in the missing dates. Each date is taken from the task's own history, where the move into that column is recorded, so the backfilled dates reflect when the move actually happened:
+
+```
+Filled in 2 missing dates:
+  bravo: started set to 2026-08-14T09:12:04.000Z (from history)
+  alpha: completed set to 2026-08-19T16:40:11.000Z (from history)
+```
+
+If a task has no history recording the move, the date falls back to the task's `updated` date, then its `created` date. The source is always reported so you can see which dates were guessed.
+
+Tasks that have a `completed` date while sitting **outside** a completed column are reported but never changed - the date records something that really happened, and removing it automatically would lose it.
+
+`kanbn board` and `kanbn status` print a one-line reminder when a board has drifted. Set `verbose: false` in your project options to suppress it.
+
+## Clearing a date
+
+There is now a way to remove a date, which is what makes the dates trustworthy as the single source of truth:
+
+```
+kanbn edit "my-task" --unset completed
+```
+
+This reopens a completed task. It works for `started`, `completed`, `due`, `plannedStart`, `plannedFinish`, `assigned`, `progress`, `tags`, and any custom field. If the same command also moves the task into a completed column, the unset is applied last, so it wins.
+
+## Per-board state fields
+
+Two new project options, `startedField` and `completedField`, name the metadata fields a board reads and writes. They default to `started` and `completed`.
+
+Pointing them at custom date fields lets one task carry separate state for separate workflows:
+
+```yaml
+completedField: designSignedOffAt
+completedColumns:
+  - Signed Off
+customFields:
+  - name: designSignedOffAt
+    type: date
+```
+
+A board configured this way writes and reads `designSignedOffAt` and leaves the shared `completed` field alone.
+
+## Other changes in 2.0.0
+
+* **Task ids ending in a single capital letter are now fully lowercased.** `kanbn add -n "Task A"` previously produced the id `task-A`; it now produces `task-a`. Non-ASCII capitals are lowercased too. Existing task files are not renamed.
+* **Unknown history event types and keys are preserved** rather than rejected, so a task file written by a newer version of kanbn stays readable.

package/docs/quick-start.md

@@ -59,4 +59,40 @@ This will add a "Large" tag to the task and modify the task's updated date. If y
 
 Run `kanbn edit --help` for more information on editing tasks.
 
-See [index structure](index-structure.md) for more information on project settings, tags and workload calculations.
+## Find tasks
+
+```
+kanbn find --tag "Large" --column "Todo"
+```
+
+Filters are combined with AND, string filters are case-insensitive regular expressions, and dates and numbers can be given twice to search a range. See [filtering and sorting](filtering-and-sorting.md) for the full model.
+
+## Customise the board
+
+Define a view in your project options to re-arrange, filter or group the board without moving any tasks:
+
+```yaml
+views:
+  - name: 'by-assignee'
+    lanes:
+      - name: 'Me'
+        filters:
+          assigned: '^my-username$'
+      - name: 'Everyone else'
+        filters:
+          assigned: '^(?!my-username$).*'
+```
+
+```
+kanbn board -v by-assignee
+```
+
+See [views](views.md) for columns, lanes, filters and sorters.
+
+## Next steps
+
+- [Index structure](index-structure.md) — project settings, tags and workload calculations
+- [Task structure](task-structure.md) — task metadata, sub-tasks, relations and comments
+- [Views](views.md) and [filtering and sorting](filtering-and-sorting.md)
+- [Advanced configuration](advanced-configuration.md) — separate config files and custom paths
+- The [`example`](../example) directory contains three ready-to-run boards you can experiment with

package/docs/task-structure.md

@@ -64,7 +64,7 @@ There should be a single level-1 heading at the top of the markdown body contain
 
 The task description should appear below the title. The description can be of any length and can contain markdown.
 
-The following level-2 headings are reserved for special purposes:
+The following level-2 headings are reserved for special purposes (`## Metadata`, `## Sub-tasks`, `## Relations`, `## Comments` and `## History`). Any other level-2 heading is treated as part of the description.
 
 ## Metadata
 
@@ -106,6 +106,8 @@ The name of the user this task is assigned to.
 
 The amount of progress for this task. This should be between 0 (not started) and 1 (complete).
 
+Progress is not derived from sub-tasks. If the task has no `progress` value it counts as 0, and a task that is considered complete always counts as 1 regardless of this value. A task is considered complete if it has a `completed` date or is in one of the [`completedColumns`](index-structure.md#completedcolumns).
+
 ### `started`
 
 The date and time that the task was started.
@@ -126,6 +128,14 @@ An optional date and time used as a preferred start point for gantt scheduling.
 
 An optional date and time used as a preferred finish point for gantt scheduling.
 
+### Custom fields
+
+Any other metadata field is preserved but otherwise ignored, unless it is declared in the [`customFields`](index-structure.md#customfields) project option. Declared custom fields can be set with `kanbn add` and `kanbn edit`, searched with `kanbn find`, sorted with `kanbn sort`, filtered in [views](views.md), and interpolated into the board's [`taskTemplate`](index-structure.md#tasktemplate).
+
+### Workload
+
+A task's workload is not stored in the file - it is calculated from the task's `tags`. It is the sum of the values of its [workload tags](index-structure.md#taskworkloadtags), or `defaultTaskWorkload` if it has none.
+
 ## Sub-tasks
 
 This should be a list of strings. Each string can optionally start with `[ ]` (incomplete) or `[x]` (completed).
@@ -134,8 +144,7 @@ This should be a list of strings. Each string can optionally start with `[ ]` (i
 
 This should be a list of links to other task files. The link text can optionally begin with a relation type.
 
-The `depends-on` relation type is reserved for gantt scheduling. It means the current task should not start until the
-linked task has finished.
+The `depends-on` relation type is reserved for gantt scheduling. It means the current task should not start until the linked task has finished.
 
 ## Comments