@basementuniverse/kanbn 2.1.0 → 2.5.0

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.
 
@@ -108,6 +123,9 @@ 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

package/docs/commands/task.txt

@@ -12,3 +12,7 @@ Options:
   {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,7 +25,9 @@ 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}
@@ -36,3 +43,9 @@ workspace-scoped option in a board file, several boards stamping the same shared
 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.

package/docs/index-structure.md

@@ -29,7 +29,57 @@ The project description should appear below the title. The description can be of
 
 Below the description there should be one or more level-2 headings. The 'Options' name is reserved for project options.
 
-All level-2 headings (except for 'Options') will be treated as columns. Columns should only contain a list of links to task markdown files.
+All level-2 headings (except for 'Options') will be treated as columns.
+
+## Column contents
+
+A column tracks a task when it contains a **markdown link** to that task's file:
+
+```markdown
+## Todo
+
+- [my-task](tasks/my-task.md)
+```
+
+That link is the only thing kanbn reads as a task. Any other line in a column - a bare title, a checkbox item, a note, a paragraph - is left exactly as you wrote it and ignored by every command:
+
+```markdown
+## Todo
+
+- [my-task](tasks/my-task.md)
+- remember to check the staging deploy
+- [ ] buy milk
+```
+
+These lines are **simple tasks**. They have no id, no metadata and no dates, they can't collide with a task of the same name, and they count towards nothing: not `kanbn status`, not workload, burndown, gantt or sprints. They are preserved when kanbn saves the board file, and stay in the column they were written in - though a line isn't anchored to the task above it, so sorting a column can move tasks around it.
+
+They are shown on the board in the default layout, dimmed, at the end of their column. Views leave them out: a view filters and sorts tasks, and a simple task has no fields to filter or sort on. They are left out of `kanbn board --json` for the same reason.
+
+### Working with simple tasks
+
+Four commands accept a simple task, addressed by its title - exactly, ignoring case, or slugified, so `"Buy milk"` and `buy-milk` both work. **A real task always wins**: kanbn only looks for a simple task when no task has that id, so a line whose title matches an existing task can only be edited by hand.
+
+| Command | Effect |
+| --- | --- |
+| `kanbn move "Buy milk" -c Done` | Moves the line to another column. `-b` moves it to another board |
+| `kanbn edit "Buy milk" ...` | **Promotes** it to a real task file, then edits it as normal |
+| `kanbn remove "Buy milk"` | Deletes the line. There is no file to delete and nothing to archive |
+| `kanbn task "Buy milk"` | Says which column it's in, and how to promote it |
+
+Promotion is one-way. The new task gets a file, an id, a `created` date as of the promotion and a `created` history event naming the column the line was in. There is no way back: a task carries metadata, comments and history that a line can't hold.
+
+Two lines with the same title on one board are two different lines, so a command naming one of them reports the ambiguity rather than guessing. Two lines with the same title on *different* boards are unrelated - a simple task belongs to the board file it's written in, and nothing else.
+
+Anything that isn't a single line of a list - a paragraph, a quote, a code block - is preserved just the same, but isn't a simple task: it isn't shown on the board, and no command will move, promote or remove it.
+
+`kanbn validate` lists them, so they can't hide. It reports two cases more loudly, because both mean a task silently isn't being tracked:
+
+- a line that looks like a task link with a typo in it, e.g. a missing closing bracket;
+- a line naming a task file that exists but isn't written as a link, e.g. `- my-task`.
+
+_Note: before version 2.2.0 a bare task id in a column (`- my-task`) was treated as a task reference. It no longer is - only links are. Run `kanbn validate` to find any, and write them as links._
+
+If a column references a task file that doesn't exist, kanbn skips that task and carries on rather than failing - this happens routinely when a board file and a task file arrive in different commits. `kanbn board` says how many tasks were skipped, and `kanbn validate` names them.
 
 ## Project options
 
@@ -37,7 +87,7 @@ The 'Options' heading should be followed by a code block containing YAML. The 'y
 
 Project options will be merged with YAML front-matter if any is present.
 
-*Note: when the index is saved, all project options will be placed into YAML front-matter. The 'Options' heading is still supported for backwards-compatibility.*
+_Note: when the index is saved, all project options will be placed into YAML front-matter. The 'Options' heading is still supported for backwards-compatibility._
 
 ```yaml
 hiddenColumns:
@@ -89,6 +139,23 @@ customFields:
     type: 'date'
 {customFieldName}Columns:
   - {Column name}
+contributors:
+  - gordon
+  - name: dave
+    displayName: Dave Smith
+    email: dave@example.com
+    aliases:
+      - Dave Smith
+    colour: '#7c5cff'
+actions:
+  - name: start-work
+    on: task.moved
+    when:
+      toColumn: In Progress
+    then:
+      - assign: '@me'
+      - addTag: active
+actionsFile: ""
 ```
 
 ### `hiddenColumns`
@@ -105,7 +172,7 @@ A list of column names. When a task is created in or dragged into one of these c
 
 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.
+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`
 
@@ -205,13 +272,13 @@ 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.*
+_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.
 
-*Note: custom fields can also be interpolated into the task template, but only if they are defined in `customFields` (see below).*
+_Note: custom fields can also be interpolated into the task template, but only if they are defined in `customFields` (see below)._
 
 ### `dateFormat`
 
@@ -234,6 +301,7 @@ An array of custom metadata fields, where each field should have `name` and `typ
 Run `kanbn add --help`, `kanbn edit --help`, `kanbn find --help` and `kanbn sort --help` for more information.
 
 Valid types are:
+
 - `boolean`
 - `date`
 - `number`
@@ -253,8 +321,8 @@ If the custom field has `updateDate` set to `always`, the field will be updated
 
 Here's an example of how this could be used:
 
-* Assume we have added a column called `Testing`
-* In `index.md` (or `kanbn.json` / `kanbn.yml` if using a separate configuration file), we have:
+- Assume we have added a column called `Testing`
+- In `index.md` (or `kanbn.json` / `kanbn.yml` if using a separate configuration file), we have:
   ```
   customFields:
     - name: testedAt
@@ -263,16 +331,56 @@ Here's an example of how this could be used:
   testedAtColumns:
     - 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.
+- 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.
+
+### `contributors`
+
+An optional list of the people who work on this workspace. Each entry is either a bare name or an object with a required `name` and optional `displayName`, `email`, `aliases` and `colour`.
+
+`contributors` is **workspace-scoped**: like `customFields`, it belongs in `kanbn.json` / `kanbn.yml`, or in the main board's front matter when there is no configuration file, and every board inherits it. A secondary board that declares its own is reported by `kanbn validate` and ignored.
+
+Contributors are **advisory**. `assigned` and comment `author` remain free text and are never validated against the list, never rejected and never rewritten. What the list buys you is a canonical spelling for each person, an autocomplete in the interactive prompts, `@me` in filters, and `kanbn contributors --usage` to find the spellings already in use.
+
+See [Contributors](contributors.md) for the full description, and `kanbn contributors --help`.
+
+### `actions`
+
+A list of rules that fire when a task is created, moved, updated, commented on, archived, restored, deleted, started or completed. Each rule names an event (`on`), an optional condition (`when`), an optional set of related tasks to act on (`for`), and the verbs to apply (`then`).
+
+```yaml
+actions:
+  - name: start-work
+    on: task.moved
+    when:
+      toColumn: In Progress
+    then:
+      - assign: '@me'
+      - addTag: active
+      - removeTag: ready
+```
+
+`actions` is board-scoped: in a configuration file it applies to every board, and in a board's front matter it applies to that board alone. A board that declares its own replaces the inherited list rather than adding to it.
+
+Rules only fire during commands that change something, and nothing a rule writes ever fires another rule. See [Actions](actions.md) for the events, the verbs, the substitutions and the failure semantics.
+
+### `actionsFile`
+
+A path, relative to the `.kanbn` folder, of a file holding the same list of rules that `actions` would have held. For rule sets that have outgrown a board's front matter.
+
+```yaml
+actionsFile: actions/design.yml
+```
+
+Setting both `actions` and `actionsFile` on the same board is an error, and so is naming a file that doesn't exist or doesn't parse.
 
 ## 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).
+- 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.
+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.
 

package/docs/index.md

@@ -10,6 +10,8 @@ To get started quickly, check out the [Quick Start](quick-start.md) guide.
 - [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
 - [Multiple Boards](multiple-boards.md) — several boards over one shared pool of tasks
+- [Contributors](contributors.md) — an optional list of who works on a workspace, and who "you" are
+- [Actions](actions.md) — declarative rules that fire when a task is created, moved, updated or finished
 - [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)
@@ -24,7 +26,7 @@ The [`example`](../example) directory contains ready-to-run workspaces:
 | [`example/basic`](../example/basic) | A typical board: columns, tags, workload, sprints |
 | [`example/views`](../example/views) | Views, lanes, filters and sorters |
 | [`example/boards`](../example/boards) | Multiple boards over one shared pool of tasks, with per-board state fields |
-| [`example/advanced`](../example/advanced) | A `kanbn.yml` config file, custom fields, column sorting and a custom task template |
+| [`example/advanced`](../example/advanced) | A `kanbn.yml` config file, custom fields, contributors, column sorting and a custom task template |
 
 Run any Kanbn command from inside one of those directories to try it out.
 

package/docs/multiple-boards.md

@@ -166,6 +166,7 @@ Some options describe the workspace rather than a single board:
 | `hiddenColumns`, `startedColumns`, `completedColumns`, `startedField`, `completedField`, `columnSorting`, `views`, `taskTemplate`, `verbose` | Board |
 | `sprints` | Workspace, overridable per board |
 | `customFields` | Workspace — task files are shared, so a field defined on one board must parse on all |
+| `contributors` | Workspace — `assigned: gordon` has to mean the same person on every board that references the task |
 | `defaultTaskWorkload`, `taskWorkloadTags` | Workspace — workload is a property of the task, not the board |
 | `dateFormat` | Workspace only — dates should read identically everywhere |
 | `mainFolder`, `indexFile`, `taskFolder`, `archiveFolder`, `defaultBoard`, `boards` | Workspace only — layout, meaningless in a board file |

package/docs/task-structure.md

@@ -100,7 +100,11 @@ An array of tags to apply to this task.
 
 ### `assigned`
 
-The name of the user this task is assigned to.
+The name of the user this task is assigned to. This is free text: any string is a valid assignee, and Kanbn never rejects or rewrites one.
+
+A workspace can declare a list of [contributors](contributors.md), which gives each person a canonical spelling, autocompletes this field in the interactive prompts and lets `kanbn find --assigned @me` work. Contributors are advisory — `assigned` stays free text either way, and a name that isn't in the list is still perfectly valid.
+
+A task has one assignee. `assigned` is a single string in the schema, the filters, the board template and the reporting commands, and there is no multiple-assignee form.
 
 ### `progress`
 
@@ -150,6 +154,8 @@ The `depends-on` relation type is reserved for gantt scheduling. It means the cu
 
 An array of comments, where each comment has an `author` and `date` property, and some text.
 
+`author` is free text, exactly like [`assigned`](#assigned), and it is optional — a comment added on a machine with no resolvable user has an empty author rather than failing to save. When the workspace declares [contributors](contributors.md), the default author is the canonical name for the current user.
+
 ## History
 
 An optional array of structured lifecycle events used for richer timeline reporting (including burndown).
@@ -168,7 +174,8 @@ Notes:
 
 - History entries are stored in the reserved `## History` section as list items.
 - `date` should be an ISO timestamp.
-- Additional fields (for example `author`) are preserved if present.
+- Every event carries an optional `author`, naming the [current user](contributors.md#the-current-user) at the time it happened. The key is omitted entirely when there is no resolvable user, so a machine with no git identity writes exactly the history it always has.
+- Any other additional field is preserved if present.
 - An event type this version of Kanbn doesn't recognise is preserved and skipped rather than rejected, so a task file written by a newer version stays readable.
 
 ### Board attribution

package/example/advanced/kanbn.yml

@@ -53,6 +53,71 @@ columnSorting:
 
 dateFormat: yyyy-mm-dd
 
+# The people who work on this workspace. A contributor can be a bare name or an
+# object; `name` is the value written into a task's `assigned` field and a
+# comment's `author`, and `aliases` catch the other spellings that mean the same
+# person. The list is advisory - `assigned` stays free text and is never
+# validated against it. Run `kanbn contributors --usage` to see which spellings
+# are already in use. See docs/contributors.md.
+contributors:
+  - name: Ana
+    email: ana@example.com
+    aliases:
+      - ana
+      - Ana Ruiz
+  - name: Ben
+    email: ben@example.com
+    aliases:
+      - ben
+
+# Rules that fire when a task changes. Actions only run during commands that
+# change something - never during `board`, `find` or `burndown` - and nothing a
+# rule writes can fire another rule. `--no-actions` on any of those commands, or
+# KANBN_NO_ACTIONS=1, steps around a rule that is misbehaving.
+# See docs/actions.md.
+actions:
+  # `task.started` is a transition rather than an operation: it fires when the
+  # task wasn't started before and is now, whatever caused it. It reads
+  # startedColumns above, so adding another started column doesn't break it.
+  - name: start-work
+    on: task.started
+    then:
+      - assign: '@me'
+      - addTag: active
+      - removeTag: ready
+
+  - name: close-out
+    on: task.completed
+    then:
+      - removeTag: active
+      - setProgress: 1
+      - set: { closedBy: '@me' }
+
+  # `reviewedAt` above is stamped by the column linkage; the rule runs after it,
+  # so it can see and override anything that stamping wrote.
+  - name: flag-review
+    on: task.moved
+    when:
+      toColumn: Review
+    then:
+      - addTag: needs-review
+      - comment: 'Review requested by @me'
+
+  # `for` points the verbs at related tasks instead of this one. Children carry
+  # the `child-of` relation, so `incoming` finds them from the epic.
+  - name: epic-blocks-children
+    on: task.moved
+    when:
+      tag: epic
+      toColumn: Blocked
+    for:
+      related: child-of
+      direction: incoming
+      where:
+        is-completed: false
+    then:
+      - addTag: blocked-by-epic
+
 # Custom fields (team, storyPoints, ...) can be interpolated here because they
 # are declared in customFields above. See docs/index-structure.md for the full
 # list of available variables.