@basementuniverse/kanbn 2.1.0 → 2.5.1

package/src/main.js

@@ -7,6 +7,8 @@ const utility = require("./utility");
 const yaml = require("yamljs");
 const humanizeDuration = require("humanize-duration");
 const rimraf = require("rimraf");
+const gitUser = require("./git-user");
+const actions = require("./actions");
 
 const DEFAULT_FOLDER_NAME = ".kanbn";
 const DEFAULT_INDEX_FILE_NAME = "index.md";
@@ -27,6 +29,7 @@ const WORKSPACE_SCOPED_OPTIONS = [
   "defaultBoard",
   "boards",
   "customFields",
+  "contributors",
   "dateFormat",
   "defaultTaskWorkload",
   "taskWorkloadTags",
@@ -161,6 +164,77 @@ function getTrackedTaskIds(index, columnName = null) {
   );
 }
 
+/**
+ * Check whether a preserved column content entry is a simple task: a single-line list item, rather
+ * than a block of prose or an empty line. Only these can be addressed from the CLI
+ * @param {object} entry A column content entry
+ * @return {boolean} True if the entry is a simple task
+ */
+function isSimpleTask(entry) {
+  return !entry.block && !!entry.text && entry.text.indexOf("\n") === -1;
+}
+
+/**
+ * Remove a preserved column content entry from a column. Positions are unique within a column, so
+ * they identify an entry
+ * @param {object} index The index object
+ * @param {string} columnName The column to remove from
+ * @param {number} position The entry's position
+ * @return {object} The modified index object
+ */
+function removeColumnContent(index, columnName, position) {
+  if (!index.columnContent || !(columnName in index.columnContent)) {
+    return index;
+  }
+  index.columnContent[columnName] = index.columnContent[columnName].filter(
+    (entry) => entry.position !== position
+  );
+  if (!index.columnContent[columnName].length) {
+    delete index.columnContent[columnName];
+  }
+  if (!Object.keys(index.columnContent).length) {
+    delete index.columnContent;
+  }
+  return index;
+}
+
+/**
+ * Add a preserved column content entry to a column
+ * @param {object} index The index object
+ * @param {string} columnName The column to add to
+ * @param {object} entry The entry to add
+ * @param {?number} [position=null] The position to add it at, or the end of the column if null
+ * @return {object} The modified index object
+ */
+function addColumnContent(index, columnName, entry, position = null) {
+  if (!index.columnContent) {
+    index.columnContent = {};
+  }
+  if (!(columnName in index.columnContent)) {
+    index.columnContent[columnName] = [];
+  }
+
+  // A position counts every entry in the column, tasks and content alike, so the end of the column
+  // is past both of them
+  const columnLength = index.columns[columnName].length + index.columnContent[columnName].length;
+  index.columnContent[columnName].push({
+    ...entry,
+    position: position === null ? columnLength : Math.max(Math.min(position, columnLength), 0),
+  });
+  return index;
+}
+
+/**
+ * Check whether a line in a column looks like a task link with a typo in it, e.g. a missing closing
+ * bracket. A checkbox item (`- [ ] ...`) is an ordinary line rather than a broken link
+ * @param {string} raw The raw line
+ * @return {boolean} True if the line looks like a malformed task link
+ */
+function looksLikeMalformedTaskLink(raw) {
+  const text = String(raw).replace(/^\s*(?:[-*+]|\d+\.)\s+/, "");
+  return /^\[/.test(text) && !/^\[[ xX]\]/.test(text);
+}
+
 /**
    * Get a task path from the id
    * @param {string} tasksPath The path to the tasks folder
@@ -303,14 +377,126 @@ function setTaskMetadata(taskData, property, value) {
   return taskData;
 }
 
+/**
+ * Work out which fields an update actually changed
+ *
+ * Reserved fields are left out: `updated` changes on every update, so including it would make the
+ * payload say nothing
+ * @param {object} before The task before the update
+ * @param {object} after The task after it
+ * @return {string[]} The names of the fields that changed
+ */
+function changedFields(before, after) {
+  const fields = new Set();
+  if (before.name !== after.name) {
+    fields.add("name");
+  }
+  if (before.description !== after.description) {
+    fields.add("description");
+  }
+  const beforeMetadata = before.metadata || {};
+  const afterMetadata = after.metadata || {};
+  for (const field of new Set([...Object.keys(beforeMetadata), ...Object.keys(afterMetadata)])) {
+    if (actions.RESERVED_FIELDS.indexOf(field) !== -1) {
+      continue;
+    }
+    if (JSON.stringify(beforeMetadata[field]) !== JSON.stringify(afterMetadata[field])) {
+      fields.add(field);
+    }
+  }
+  return [...fields];
+}
+
+/**
+ * Normalise a contributors option into a consistent object form
+ *
+ * A contributor can be written as a bare name or as an object, and both mean the same thing - the
+ * shorthand is what most workspaces will ever need, and requiring `- name: gordon` for a bare name
+ * is the kind of ceremony that stops an optional feature being adopted. Everything downstream sees
+ * the object form
+ * @param {any} contributors The raw contributors option
+ * @return {object[]} The normalised contributors
+ */
+function normaliseContributors(contributors) {
+  if (!Array.isArray(contributors)) {
+    return [];
+  }
+  const result = [];
+  for (const contributor of contributors) {
+    const source = typeof contributor === "string" ? { name: contributor } : contributor;
+    if (source === null || typeof source !== "object" || typeof source.name !== "string") {
+      continue;
+    }
+    const name = source.name.trim();
+    if (!name) {
+      continue;
+    }
+    const normalised = {
+      name,
+      displayName: typeof source.displayName === "string" && source.displayName ? source.displayName : name,
+      aliases: Array.isArray(source.aliases)
+        ? source.aliases.filter((alias) => typeof alias === "string" && alias.trim()).map((alias) => alias.trim())
+        : [],
+    };
+    if (typeof source.email === "string" && source.email) {
+      normalised.email = source.email;
+    }
+
+    // Purely presentational, for avatar chips in a UI. Kanbn stores and serves it, and never
+    // interprets it
+    if (typeof source.colour === "string" && source.colour) {
+      normalised.colour = source.colour;
+    }
+    result.push(normalised);
+  }
+  return result;
+}
+
+/**
+ * Find the contributor a value refers to, matching against the canonical name, the display name and
+ * any aliases, case-insensitively
+ * @param {object[]} contributors Normalised contributors
+ * @param {?string} value The value to look up
+ * @return {?object} The matching contributor, or null if there isn't one
+ */
+function matchContributor(contributors, value) {
+  if (typeof value !== "string" || !value.trim()) {
+    return null;
+  }
+  const needle = value.trim().toLowerCase();
+  return (
+    contributors.find(
+      (contributor) =>
+        contributor.name.toLowerCase() === needle ||
+        contributor.displayName.toLowerCase() === needle ||
+        contributor.aliases.some((alias) => alias.toLowerCase() === needle)
+    ) || null
+  );
+}
+
+/**
+ * Find the contributor with a given email address, case-insensitively
+ * @param {object[]} contributors Normalised contributors
+ * @param {?string} email The email address to look up
+ * @return {?object} The matching contributor, or null if there isn't one
+ */
+function matchContributorEmail(contributors, email) {
+  if (typeof email !== "string" || !email.trim()) {
+    return null;
+  }
+  const needle = email.trim().toLowerCase();
+  return contributors.find((contributor) => (contributor.email || "").toLowerCase() === needle) || null;
+}
+
 /**
  * Append a structured history event to a task
  * @param {object} taskData The task object
  * @param {object} historyEvent The history event payload
  * @param {?string} [boardSlug=null] The board the event happened on, or null for the main board
+ * @param {?string} [author=null] The user the event is attributed to, or null for no attribution
  * @return {object} The modified task object
  */
-function appendTaskHistory(taskData, historyEvent, boardSlug = null) {
+function appendTaskHistory(taskData, historyEvent, boardSlug = null, author = null) {
   if (!('history' in taskData) || taskData.history === null) {
     taskData.history = [];
   }
@@ -320,17 +506,14 @@ function appendTaskHistory(taskData, historyEvent, boardSlug = null) {
 
     // Events on the main board carry no board key, so a single-board workspace writes exactly the
     // history it always has
-    ...(boardSlug === null ? {} : { board: boardSlug })
+    ...(boardSlug === null ? {} : { board: boardSlug }),
+
+    // Likewise, a machine with no resolvable user writes no author key at all
+    ...(author ? { author } : {})
   });
   return taskData;
 }
 
-/**
- * Check if a task is completed
- * @param {object} index
- * @param {object} task
- * @return {boolean} True if the task is in a completed column or has a completed date
- */
 /**
  * Get the name of the metadata field that holds a task's started date for this board. Boards can
  * point this at a custom date field so that several boards can track their own started/completed
@@ -351,10 +534,75 @@ function getCompletedField(index) {
   return ("completedField" in index.options && index.options.completedField) || DEFAULT_COMPLETED_FIELD;
 }
 
+/**
+ * Find the column a task is currently in
+ * @param {object} index The index object
+ * @param {object} task The task object
+ * @return {?string} The column name, or null if the task isn't in the index
+ */
+function getTaskColumn(index, task) {
+  return findTaskColumn(index, task.id || utility.getTaskId(task.name));
+}
+
+/**
+ * Check if a task has been started, based on its metadata
+ * @param {object} index The index object
+ * @param {object} task The task object
+ * @return {boolean} True if the task has a started date
+ */
+function taskStarted(index, task) {
+  return getStartedField(index) in task.metadata;
+}
+
+/**
+ * Check if a task is completed, based on its metadata
+ * @param {object} index The index object
+ * @param {object} task The task object
+ * @return {boolean} True if the task has a completed date
+ */
 function taskCompleted(index, task) {
   return getCompletedField(index) in task.metadata;
 }
 
+/**
+ * Check if a task is in one of this board's started columns. A board that declares no
+ * startedColumns has no notion of work in progress, so nothing is in a started column
+ * @param {object} index The index object
+ * @param {object} task The task object
+ * @return {boolean} True if the task is in a started column
+ */
+function taskInStartedColumn(index, task) {
+  const startedColumns = "startedColumns" in index.options ? index.options.startedColumns : [];
+  const column = getTaskColumn(index, task);
+  return column !== null && startedColumns.indexOf(column) !== -1;
+}
+
+/**
+ * Check if a task is in one of this board's completed columns
+ * @param {object} index The index object
+ * @param {object} task The task object
+ * @return {boolean} True if the task is in a completed column
+ */
+function taskInCompletedColumn(index, task) {
+  const completedColumns = "completedColumns" in index.options ? index.options.completedColumns : [];
+  const column = getTaskColumn(index, task);
+  return column !== null && completedColumns.indexOf(column) !== -1;
+}
+
+/**
+ * Check if a task is overdue - i.e. it has a due date in the past and hasn't been completed. A task
+ * with no due date is never overdue, and neither is a completed task, however late it was
+ * @param {object} index The index object
+ * @param {object} task The task object
+ * @return {boolean} True if the task is overdue
+ */
+function taskOverdue(index, task) {
+  if (!("due" in task.metadata) || taskCompleted(index, task)) {
+    return false;
+  }
+  return new Date() - task.metadata.due > 0;
+}
+
 /**
  * Flatten a task's metadata and computed values into a single object that can be used for sorting
  * @param {object} index The index object
@@ -383,6 +631,12 @@ function taskSortFields(index, task) {
     comments: task.comments.map((comment) => `${comment.author} ${comment.text}`).join("\n"),
     workload: taskWorkload(index, task),
     progress: taskProgress(index, task),
+    column: getTaskColumn(index, task) || "",
+    overdue: taskOverdue(index, task),
+    isStarted: taskStarted(index, task),
+    isCompleted: taskCompleted(index, task),
+    inStartedColumn: taskInStartedColumn(index, task),
+    inCompletedColumn: taskInCompletedColumn(index, task),
   };
 }
 
@@ -416,8 +670,11 @@ function sortColumnInIndex(index, tasks, columnName, sorters) {
   // Sort the tasks in the target column using their flattened sort fields
   tasks = sortTasksWithFields(index, tasks, sorters);
 
-  // Save the list of tasks back to the index
-  index.columns[columnName] = tasks.map((task) => task.id);
+  // Save the list of tasks back to the index. A task whose file is missing can't be loaded, so it
+  // isn't in the sorted list - keep it in the column rather than dropping it from the board
+  const sortedTaskIds = tasks.map((task) => task.id);
+  const unsortedTaskIds = index.columns[columnName].filter((taskId) => sortedTaskIds.indexOf(taskId) === -1);
+  index.columns[columnName] = [...sortedTaskIds, ...unsortedTaskIds];
   return index;
 }
 
@@ -596,6 +853,37 @@ function filterTasks(index, tasks, filters) {
       result = false;
     }
 
+    // Overdue
+    if ("overdue" in filters && !booleanFilter(filters.overdue, taskOverdue(index, task))) {
+      result = false;
+    }
+
+    // Started, from the task's metadata
+    if ("is-started" in filters && !booleanFilter(filters["is-started"], taskStarted(index, task))) {
+      result = false;
+    }
+
+    // Completed, from the task's metadata
+    if ("is-completed" in filters && !booleanFilter(filters["is-completed"], taskCompleted(index, task))) {
+      result = false;
+    }
+
+    // In a started column on this board
+    if (
+      "in-started-column" in filters &&
+      !booleanFilter(filters["in-started-column"], taskInStartedColumn(index, task))
+    ) {
+      result = false;
+    }
+
+    // In a completed column on this board
+    if (
+      "in-completed-column" in filters &&
+      !booleanFilter(filters["in-completed-column"], taskInCompletedColumn(index, task))
+    ) {
+      result = false;
+    }
+
     // Assigned
     if (
       "assigned" in filters &&
@@ -743,6 +1031,17 @@ function numberFilter(filter, input) {
   return input >= Math.min(...filter) && input <= Math.max(...filter);
 }
 
+/**
+ * Check if the input matches a boolean, or if multiple booleans are passed in, check if the input
+ * matches any of them
+ * @param {boolean|boolean[]} filter A filter boolean or array of filter booleans
+ * @param {boolean} input The value to match against
+ * @return {boolean} True if the input matches the boolean filter
+ */
+function booleanFilter(filter, input) {
+  return utility.arrayArg(filter).some((value) => !!value === !!input);
+}
+
 /**
  * Calculate task workload
  * @param {object} index The index object
@@ -1387,6 +1686,16 @@ function updateColumnLinkedCustomField(
   return taskData;
 }
 
+// The parts of this module the actions engine needs. Passing them in rather than requiring main.js
+// from actions.js keeps the engine free of filesystem and workspace knowledge, and free of a
+// circular require
+const ACTION_HELPERS = {
+  filterTasks,
+  getTaskMetadata,
+  setTaskMetadata,
+  appendTaskHistory
+};
+
 class Kanbn {
   ROOT = process.cwd();
   CONFIG_YAML = path.join(this.ROOT, "kanbn.yml");
@@ -1399,6 +1708,14 @@ class Kanbn {
   // restoreTask() for the caller to report
   lastRestoreWarnings = [];
 
+  // Rules that were skipped during the last operation, set by runActions() for the caller to report
+  lastActionWarnings = [];
+
+  // Whether scripted actions run for operations on this instance. Actions are ordinary declarative
+  // rules with no code execution, so this is a convenience for stepping around a misbehaving rule
+  // rather than a safety control
+  actionsEnabled = true;
+
   /**
    * @param {?string} [root=null] The workspace root folder
    * @param {object} [options={}] Instance options: `board` scopes this instance to a board, `caches`
@@ -1412,6 +1729,9 @@ class Kanbn {
     }
     this.caches = options.caches || { config: null, workspaceOptions: null };
     this.boardSlug = options.board || null;
+    if (options.actions === false) {
+      this.actionsEnabled = false;
+    }
   }
 
   // Memoized config, kept in the shared cache object so that board-scoped clones don't each re-read it
@@ -1431,9 +1751,29 @@ class Kanbn {
    */
   board(slug = null) {
     if (slug === null || slug === undefined || slug === "") {
-      return this.boardSlug === null ? this : new Kanbn(this.ROOT, { caches: this.caches });
+      return this.boardSlug === null
+        ? this
+        : new Kanbn(this.ROOT, { caches: this.caches, actions: this.actionsEnabled });
+    }
+    return new Kanbn(this.ROOT, {
+      board: String(slug).trim(),
+      caches: this.caches,
+      actions: this.actionsEnabled
+    });
+  }
+
+  /**
+   * Get an instance that runs no actions
+   *
+   * Used for the writes one operation makes on another's behalf - archiving removes the task from
+   * every board, and that removal is part of the archive, not a deletion anyone wrote a rule for
+   * @return {Kanbn} An instance with actions disabled
+   */
+  withoutActions() {
+    if (!this.actionsEnabled) {
+      return this;
     }
-    return new Kanbn(this.ROOT, { board: String(slug).trim(), caches: this.caches });
+    return new Kanbn(this.ROOT, { board: this.boardSlug, caches: this.caches, actions: false });
   }
 
   /**
@@ -1673,8 +2013,6 @@ class Kanbn {
     if ("due" in task.metadata) {
       const dueData = {};
 
-      // A task is overdue if it's due date is in the past and the task is not in a completed column
-      // or doesn't have a completed dates
       const completedField = getCompletedField(index);
       const completedDate = completedField in task.metadata ? task.metadata[completedField] : null;
 
@@ -1691,7 +2029,7 @@ class Kanbn {
       dueData.completed = completed;
       dueData.completedDate = completedDate;
       dueData.dueDate = task.metadata.due;
-      dueData.overdue = !completed && delta > 0;
+      dueData.overdue = taskOverdue(index, task);
       dueData.dueDelta = delta;
 
       // Prepare a due message for the task
@@ -1760,6 +2098,76 @@ class Kanbn {
     return this.caches.workspaceOptions;
   }
 
+  /**
+   * Normalise a contributors option into a consistent object form. Exposed so that callers holding
+   * an index object (the VSCode extension, for one) don't have to reimplement the shorthand rules
+   * @param {any} contributors The raw contributors option
+   * @return {object[]} The normalised contributors
+   */
+  normaliseContributors(contributors) {
+    return normaliseContributors(contributors);
+  }
+
+  /**
+   * Get the workspace's contributors, normalised to the object form
+   *
+   * Contributors are advisory: they're a convenience list, not an access control list, and nothing
+   * anywhere validates `assigned` or a comment `author` against them
+   * @return {Promise<object[]>} The normalised contributors, or an empty array if none are declared
+   */
+  async getContributors() {
+    return normaliseContributors((await this.getWorkspaceOptions()).contributors);
+  }
+
+  /**
+   * Find the contributor a value refers to, matching against the canonical name, the display name
+   * and any aliases, case-insensitively
+   * @param {?string} value The value to look up
+   * @return {Promise<?object>} The matching contributor, or null if there isn't one
+   */
+  async findContributor(value) {
+    return matchContributor(await this.getContributors(), value);
+  }
+
+  /**
+   * Work out who the current user is, as the value that would be written into `assigned` or a
+   * comment `author`
+   *
+   * In order, first match wins:
+   *  1. the KANBN_USER environment variable, used verbatim
+   *  2. `git config user.email` matched against a contributor's email
+   *  3. `git config user.name` matched against a contributor's name, display name or aliases
+   *  4. `git config user.name` as-is
+   *  5. null
+   *
+   * With no contributors declared this is exactly what the git username has always been, so a
+   * workspace that ignores contributors sees no change. With contributors declared it canonicalises:
+   * a machine whose git says "Gordon Larrigan" writes "gordon", because that's what the workspace has
+   * agreed to call him
+   * @return {Promise<?string>} The current user, or null if there's nothing to go on
+   */
+  async currentUser() {
+    // An explicitly set user is used exactly as given - it's the escape hatch for a machine whose
+    // git identity is wrong, or which has none
+    const envUser = (process.env.KANBN_USER || "").trim();
+    if (envUser) {
+      return envUser;
+    }
+
+    const contributors = await this.getContributors();
+    if (contributors.length) {
+      const byEmail = matchContributorEmail(contributors, gitUser.email());
+      if (byEmail !== null) {
+        return byEmail.name;
+      }
+      const byName = matchContributor(contributors, gitUser.name());
+      if (byName !== null) {
+        return byName.name;
+      }
+    }
+    return gitUser.name();
+  }
+
   /**
    * Get the options a secondary board inherits from the workspace. A config file is workspace-level
    * by construction, so all of it is inherited; the main board's front matter is that board's own
@@ -1978,11 +2386,262 @@ class Kanbn {
     const result = [];
     const trackedTasks = getTrackedTaskIds(index, columnName);
     for (let taskId of trackedTasks) {
-      result.push(await this.loadTask(taskId));
+      try {
+        result.push(await this.loadTask(taskId));
+      } catch (error) {
+
+        // A board referencing a task file that doesn't exist is a broken reference, not a reason to
+        // fail: it happens whenever a board file and a task file arrive in different commits. Skip
+        // it and carry on - findMissingTaskFiles() and validate report it. Anything else (an
+        // unreadable or unparseable file) still throws, because that is a file with contents that
+        // can't be trusted rather than a file that isn't there
+        if (!(await this.taskFileExists(taskId))) {
+          continue;
+        }
+        throw error;
+      }
     }
     return result;
   }
 
+  /**
+   * Find tasks that this board references but which have no task file
+   * @param {?object} [index=null] The index object, or null to load it
+   * @return {Promise<object[]>} A list of {task, column} for each missing task file
+   */
+  async findMissingTaskFiles(index = null) {
+    if (index === null) {
+      index = await this.getIndex();
+    }
+    const missing = [];
+    for (const [columnName, taskIds] of Object.entries(index.columns)) {
+      for (const taskId of taskIds) {
+        if (!(await this.taskFileExists(taskId))) {
+          missing.push({ task: taskId, column: columnName });
+        }
+      }
+    }
+    return missing;
+  }
+
+  /**
+   * Get this board's simple tasks - lines in a column that aren't task links. A simple task has a
+   * title and a column and nothing else: no id, no metadata, no dates, and no presence in any of
+   * kanbn's reporting. It can be moved, removed, or promoted into a real task
+   *
+   * When an input string is given, this returns the simple tasks matching it. Real tasks always win,
+   * so callers should resolve a task id first and only fall back to this when nothing matched
+   * @param {?string} [input=null] A title to match, or null for every simple task on this board
+   * @param {?object} [index=null] The index object, or null to load it
+   * @return {Promise<object[]>} The matching simple tasks, each with a column, position and text
+   */
+  async findSimpleTasks(input = null, index = null) {
+    if (index === null) {
+      index = await this.getIndex();
+    }
+    const simpleTasks = [];
+    for (const [columnName, entries] of Object.entries(index.columnContent || {})) {
+      for (const entry of entries) {
+        if (isSimpleTask(entry)) {
+          simpleTasks.push({ column: columnName, position: entry.position, text: entry.text, raw: entry.raw });
+        }
+      }
+    }
+    if (input === null) {
+      return simpleTasks;
+    }
+
+    // Match on the title exactly first, then ignoring case, then on the slugified title, so that
+    // `kanbn move "Buy milk"` and `kanbn move buy-milk` both find the same line
+    const matchers = [
+      (simpleTask) => simpleTask.text === input,
+      (simpleTask) => simpleTask.text.toLowerCase() === String(input).toLowerCase(),
+      (simpleTask) => utility.getTaskId(simpleTask.text) === utility.getTaskId(String(input)),
+    ];
+    for (const matcher of matchers) {
+      const matches = simpleTasks.filter(matcher);
+      if (matches.length) {
+        return matches;
+      }
+    }
+    return [];
+  }
+
+  /**
+   * Resolve a string to exactly one simple task on this board, or throw
+   * @param {string} input The title to match
+   * @param {?object} [index=null] The index object, or null to load it
+   * @return {Promise<object>} The matching simple task
+   */
+  async getSimpleTask(input, index = null) {
+    const matches = await this.findSimpleTasks(input, index);
+    if (!matches.length) {
+      throw new Error(`No simple task found matching "${input}"`);
+    }
+
+    // Two lines with the same title are two different lines, and picking one of them silently would
+    // eventually move or delete the wrong one
+    if (matches.length > 1) {
+      throw new Error(
+        `"${input}" matches ${matches.length} simple tasks (${matches
+          .map((match) => `"${match.text}" in ${match.column}`)
+          .join(", ")})`
+      );
+    }
+    return matches[0];
+  }
+
+  /**
+   * Move a simple task to another column on this board
+   * @param {string} input The title to match
+   * @param {string} columnName The column to move it to
+   * @param {?number} [position=null] The position in the target column, or the end of it if null
+   * @return {Promise<object>} The simple task that was moved, with the column it came from
+   */
+  async moveSimpleTask(input, columnName, position = null) {
+    let index = await this.getIndex();
+    if (!(columnName in index.columns)) {
+      throw new Error(`Column "${columnName}" doesn't exist`);
+    }
+    const simpleTask = await this.getSimpleTask(input, index);
+    index = removeColumnContent(index, simpleTask.column, simpleTask.position);
+    index = addColumnContent(index, columnName, { text: simpleTask.text, raw: simpleTask.raw }, position);
+    await this.saveIndex(index);
+    return { ...simpleTask, toColumn: columnName };
+  }
+
+  /**
+   * Move a simple task from this board onto another one. A simple task is content in a board file
+   * rather than a shared task file, so this moves the line: it leaves this board and joins the other
+   * @param {string} input The title to match
+   * @param {string} targetSlug The board to move it to
+   * @param {?string} [columnName=null] The column on the target board, or its first column if null
+   * @param {?number} [position=null] The position in the target column, or the end of it if null
+   * @return {Promise<object>} The simple task that was moved, with the board and column it went to
+   */
+  async moveSimpleTaskToBoard(input, targetSlug, columnName = null, position = null) {
+    const target = this.board(targetSlug);
+    const targetBoardSlug = await target.resolveBoardSlug();
+    if (!(await target.initialised())) {
+      throw new Error(`Board "${targetBoardSlug}" doesn't exist`);
+    }
+    if (targetBoardSlug === (await this.resolveBoardSlug())) {
+      throw new Error(`Simple task "${input}" is already on board "${targetBoardSlug}"`);
+    }
+    let index = await this.getIndex();
+    const simpleTask = await this.getSimpleTask(input, index);
+    let targetIndex = await target.getIndex();
+    const targetColumnNames = Object.keys(targetIndex.columns);
+    if (!targetColumnNames.length) {
+      throw new Error(`Board "${targetBoardSlug}" has no columns`);
+    }
+    const targetColumn = columnName === null ? targetColumnNames[0] : columnName;
+    if (!(targetColumn in targetIndex.columns)) {
+      throw new Error(`Column "${targetColumn}" doesn't exist on board "${targetBoardSlug}"`);
+    }
+
+    // Write the target board first: a line that ends up on both boards is visible and easy to fix,
+    // where a line removed from one board and never added to the other is gone
+    targetIndex = addColumnContent(
+      targetIndex,
+      targetColumn,
+      { text: simpleTask.text, raw: simpleTask.raw },
+      position
+    );
+    await target.saveIndex(targetIndex);
+    index = removeColumnContent(index, simpleTask.column, simpleTask.position);
+    await this.saveIndex(index);
+    return { ...simpleTask, toBoard: targetBoardSlug, toColumn: targetColumn };
+  }
+
+  /**
+   * Remove a simple task from this board. There is no file to delete and nothing to archive - the
+   * line is the whole of it
+   * @param {string} input The title to match
+   * @return {Promise<object>} The simple task that was removed
+   */
+  async deleteSimpleTask(input) {
+    let index = await this.getIndex();
+    const simpleTask = await this.getSimpleTask(input, index);
+    index = removeColumnContent(index, simpleTask.column, simpleTask.position);
+    await this.saveIndex(index);
+    return simpleTask;
+  }
+
+  /**
+   * Turn a simple task into a real task file, in the column it was already in. The created date is
+   * the moment of promotion: a line carries no history, so there is no earlier date to know
+   * @param {string} input The title to match
+   * @param {?string} [columnName=null] The column to create the task in, or its own column if null
+   * @return {Promise<string>} The id of the task that was created
+   */
+  async promoteSimpleTask(input, columnName = null) {
+    const index = await this.getIndex();
+    const simpleTask = await this.getSimpleTask(input, index);
+    const targetColumn = columnName === null ? simpleTask.column : columnName;
+    if (!(targetColumn in index.columns)) {
+      throw new Error(`Column "${targetColumn}" doesn't exist`);
+    }
+
+    // Check for a clash before writing anything, so that a promotion that can't happen doesn't take
+    // the line with it
+    const taskId = utility.getTaskId(simpleTask.text);
+    if (await this.taskFileExists(taskId)) {
+      throw new Error(`A task with id "${taskId}" already exists`);
+    }
+    if (taskInIndex(index, taskId)) {
+      throw new Error(`A task with id "${taskId}" is already in the index`);
+    }
+
+    // Create the task first: a leftover line beside a real task is reported by validate and is easy
+    // to fix, where a line deleted for a task that was never created is gone
+    await this.createTask({ name: simpleTask.text }, targetColumn);
+    await this.saveIndex(removeColumnContent(await this.getIndex(), simpleTask.column, simpleTask.position));
+    return taskId;
+  }
+
+  /**
+   * Find lines in this board's columns that aren't task links. These are preserved verbatim and
+   * ignored by every command, but a line that looks like it was meant to be a task link is worth
+   * pointing out - it's the one way a task can silently stop being tracked
+   * @param {?object} [index=null] The index object, or null to load it
+   * @return {Promise<object[]>} A list of warnings, each with a board, column, type and message
+   */
+  async findColumnContentWarnings(index = null) {
+    if (index === null) {
+      index = await this.getIndex();
+    }
+    const boardSlug = await this.resolveBoardSlug();
+    const warnings = [];
+    for (const [columnName, entries] of Object.entries(index.columnContent || {})) {
+      for (const entry of entries) {
+
+        // A line that starts with link punctuation was probably meant to be a task link and has a
+        // typo in it, which would otherwise look exactly like a task that has vanished from the
+        // board. A checkbox item is an ordinary line, not a broken link
+        let type = "non-task-line";
+        let message = `column "${columnName}" contains a line that isn't a task link: ${entry.raw}`;
+        if (looksLikeMalformedTaskLink(entry.raw)) {
+          type = "malformed-task-link";
+          message = `column "${columnName}" contains a line that looks like a malformed task link: ${entry.raw}`;
+
+          // A line naming a task file that exists is almost certainly a task the user expects to be
+          // tracked, written without the link. It isn't, and this is the only warning that says so
+        } else if (
+          (await this.taskFileExists(entry.text)) ||
+          (await this.taskFileExists(utility.getTaskId(entry.text)))
+        ) {
+          type = "untracked-task-line";
+          message =
+            `column "${columnName}" contains a line naming a task file that exists, but it isn't a ` +
+            `link so the task isn't tracked: ${entry.raw}`;
+        }
+        warnings.push({ board: boardSlug, column: columnName, type, text: entry.text, message });
+      }
+    }
+    return warnings;
+  }
+
   /**
    * Load a task file from the archive and parse it to an object
    * @param {string} taskId The task id
@@ -2237,6 +2896,328 @@ class Kanbn {
     return (await this.isMainBoard()) ? null : await this.resolveBoardSlug();
   }
 
+  /**
+   * Get the action rules that apply to this board
+   *
+   * Rules layer like any other option: a config file value applies workspace-wide, a board's own
+   * front matter applies to that board. `actionsFile` points at a file holding the same list, for
+   * workspaces whose rule sets have outgrown their front matter
+   * @param {?object} [index=null] The index object, or null to load it
+   * @return {Promise<object[]>} The rules
+   */
+  async getActionRules(index = null) {
+    if (index === null) {
+      index = await this.getIndex();
+    }
+    const options = index.options || {};
+    const inlineActions = "actions" in options && options.actions !== null;
+    const actionsFile = "actionsFile" in options && options.actionsFile ? String(options.actionsFile) : null;
+
+    // One overriding or extending the other would invent a second merge rule for the sake of a case
+    // nobody needs, so having both is an error the author has to resolve
+    if (inlineActions && actionsFile !== null) {
+      throw new Error('"actions" and "actionsFile" can\'t both be set - use one or the other');
+    }
+    if (actionsFile !== null) {
+      const filePath = path.join(await this.getMainFolder(), actionsFile);
+      if (!(await exists(filePath))) {
+        throw new Error(`actionsFile "${actionsFile}" doesn't exist`);
+      }
+
+      // A rule set that quietly stops existing is worse than one that fails loudly, so an
+      // unreadable or unparseable file is an error rather than "no rules"
+      return actions.parseActionsFile(await fs.promises.readFile(filePath, { encoding: "utf-8" }), actionsFile);
+    }
+    return actions.normaliseRules(options.actions || []);
+  }
+
+  /**
+   * Check whether actions should run at all
+   * @return {boolean} True if actions are enabled
+   */
+  actionsAllowed() {
+    if (!this.actionsEnabled) {
+      return false;
+    }
+    const disabled = process.env.KANBN_NO_ACTIONS;
+    return !(disabled && disabled !== "0" && disabled !== "false");
+  }
+
+  /**
+   * Get the value to record in a history event's `board` key for another board
+   * @param {string} slug The board slug
+   * @return {Promise<?string>} The board slug, or null for the main board
+   */
+  async historyBoardFor(slug) {
+    return slug === (await this.getMainBoardSlug()) ? null : slug;
+  }
+
+  /**
+   * Run the rules that match an event and fold everything they produce into the in-memory state
+   *
+   * Nothing is written here. Every verb becomes a patch to a task or to the index that the operation
+   * was already going to write, which is what makes a rule that fails leave the workspace alone, and
+   * what makes "actions never fire actions" structural: the writes this produces are performed with
+   * no event assembly at all
+   * @param {object} params The event, the in-memory index and task, and the operation's timestamp
+   * @return {Promise<?object>} The action result, or null if no rules ran
+   */
+  async runActions({ eventTypes, index, taskId, taskData, payload, date, taskBoards = null }) {
+    this.lastActionWarnings = [];
+    if (!this.actionsAllowed()) {
+      return null;
+    }
+    const boardSlug = await this.resolveBoardSlug();
+
+    // A task on its way to being created hasn't been through the parser yet, so it has no id. The
+    // filter vocabulary and the relation graph are both keyed on it
+    if (!taskData.id) {
+      taskData.id = taskId;
+    }
+    const rules = await this.getActionRules(index);
+
+    // Archiving, restoring and deleting affect every board, so the board a command happened to be
+    // run from is an arbitrary choice of whose rules to fire. A rule elsewhere can opt in to hearing
+    // about them whoever triggered them - which is why this is collected before the early return:
+    // a board with no rules of its own can still be the one an archive was run from
+    let borrowed = [];
+    if (
+      taskBoards !== false &&
+      eventTypes.some((eventType) => actions.WORKSPACE_WIDE_EVENTS.indexOf(eventType) !== -1) &&
+      (await this.listBoards()).length > 1
+    ) {
+      borrowed = await this.borrowedActionRules(taskId, boardSlug, eventTypes, taskBoards);
+    }
+    if (!rules.length && !borrowed.length) {
+      return null;
+    }
+
+    // Configuration errors fail the operation before anything is written. Checking the whole rule
+    // set rather than just the matching rules means a typo is reported the first time any command
+    // runs, not the first time that one rule would have fired
+    if (rules.length) {
+      const context = { columns: Object.keys(index.columns) };
+      if (
+        rules.some(
+          (rule) =>
+            Array.isArray(rule.then) &&
+            rule.then.some((verb) => verb !== null && typeof verb === "object" && "addToBoard" in verb)
+        )
+      ) {
+        context.boards = (await this.listBoards()).map((board) => board.slug);
+      }
+      const errors = actions.findRuleErrors(rules, context);
+      if (errors.length) {
+        throw new Error(`Invalid actions:${errors.map((error) => `\n  ${error}`).join("")}`);
+      }
+    }
+
+    // This board's rules run first, then the ones that asked to listen from elsewhere
+    const relevant = [...rules.filter((rule) => eventTypes.indexOf(rule.on) !== -1), ...borrowed];
+    if (!relevant.length) {
+      return null;
+    }
+    const result = await actions.run({
+      rules: relevant,
+      eventTypes,
+      payload: { ...payload, board: boardSlug, boardSlug, isMainBoard: await this.isMainBoard() },
+      index,
+      task: taskData,
+      date,
+      user: await this.currentUser(),
+      boardSlug,
+      helpers: ACTION_HELPERS,
+      loadTask: async (id) => {
+        try {
+          return await this.loadTask(id);
+        } catch (error) {
+          return null;
+        }
+      },
+      loadAllTasks: async () => await this.loadAllTrackedTasks(index)
+    });
+
+    // Appended rather than replaced: collecting the rules can warn too, and those warnings matter
+    this.lastActionWarnings.push(...result.warnings);
+
+    // Board memberships and cross-task moves are recorded in the task's history the same way the
+    // equivalent manual operations are, attributed to the rule rather than to a person
+    for (const add of result.patch.boardAdds) {
+      taskData = appendTaskHistory(
+        taskData,
+        { date, type: "added", column: add.column },
+        await this.historyBoardFor(add.board),
+        add.author
+      );
+    }
+    for (const target of result.targets) {
+      for (const add of target.boardAdds) {
+        target.task = appendTaskHistory(
+          target.task,
+          { date, type: "added", column: add.column },
+          await this.historyBoardFor(add.board),
+          add.author
+        );
+      }
+      if (target.moveTo === null) {
+        continue;
+      }
+
+      // A target that isn't on this board has no row in this index to move, and a target already in
+      // the column it would be moved to is a no-op rather than an event
+      if (!taskInIndex(index, target.task.id)) {
+        this.lastActionWarnings.push(
+          `skipped moving "${target.task.id}": it isn't on board "${boardSlug}"`
+        );
+        target.moveTo = null;
+        continue;
+      }
+      const fromColumn = findTaskColumn(index, target.task.id);
+      if (fromColumn === target.moveTo.column) {
+        target.moveTo = null;
+        continue;
+      }
+      target.task = appendTaskHistory(
+        target.task,
+        { date, type: "moved", fromColumn, toColumn: target.moveTo.column },
+        await this.historyBoard(),
+        target.moveTo.author
+      );
+      target.task = setTaskMetadata(target.task, "updated", date);
+      index = removeTaskFromIndex(index, target.task.id);
+      index = addTaskToIndex(index, target.task.id, target.moveTo.column, target.moveTo.position);
+    }
+    result.index = index;
+    result.taskData = taskData;
+    return result;
+  }
+
+  /**
+   * Collect the rules on other boards that have opted in to hearing about a workspace-wide event
+   *
+   * Board membership is per-board data and can't conflict, but rule verbs write the single shared
+   * task file, where two boards' rules genuinely can. So the acting board decides what gets written
+   * by default, and a rule elsewhere has to say that it wants to listen
+   * @param {string} taskId The task the event fired for
+   * @param {string} boardSlug The acting board
+   * @param {string[]} eventTypes The events that fired
+   * @param {?string[]} [knownBoards=null] The boards this operation affects, when the index can't say
+   * @return {Promise<object[]>} The rules to run after this board's own
+   */
+  async borrowedActionRules(taskId, boardSlug, eventTypes, knownBoards = null) {
+    // A task being restored isn't on any board yet, so the caller has to say which boards it is
+    // about to rejoin. Everywhere else the index is the authority
+    const taskBoards = (knownBoards === null
+      ? Object.keys(await this.findTaskBoards(taskId))
+      : knownBoards
+    ).filter((slug) => slug !== boardSlug);
+    if (!taskBoards.length) {
+      return [];
+    }
+
+    // Board order is whatever `kanbn boards` shows, so which rule wins when two of them write the
+    // same field is at least stable and inspectable
+    const ordered = (await this.listBoards()).map((board) => board.slug).filter((slug) => taskBoards.indexOf(slug) !== -1);
+    const borrowed = [];
+    for (const slug of ordered) {
+      const otherBoard = this.board(slug);
+      let otherRules = [];
+      try {
+        otherRules = await otherBoard.getActionRules();
+      } catch (error) {
+        this.lastActionWarnings.push(`skipped board "${slug}" rules: ${error.message}`);
+        continue;
+      }
+      const listening = otherRules.filter((rule) => rule.anyBoard === true && eventTypes.indexOf(rule.on) !== -1);
+      if (!listening.length) {
+        continue;
+      }
+
+      // Another board's mistake shouldn't fail a command that didn't ask for that board. Its rules
+      // are skipped instead, and kanbn validate --all-boards reports why
+      const errors = actions.findRuleErrors(listening, {
+        columns: Object.keys((await otherBoard.getIndex()).columns)
+      });
+      if (errors.length) {
+        this.lastActionWarnings.push(`skipped board "${slug}" rules: ${errors[0]}`);
+        continue;
+      }
+      borrowed.push(...listening);
+    }
+    return borrowed;
+  }
+
+  /**
+   * Write the task files and board memberships a rule asked for
+   *
+   * These come after the operation's own writes because they are separate files: the patches were
+   * all computed before anything was written, so a failure here can't leave a half-applied rule
+   * @param {?object} result The action result, or null if no rules ran
+   * @param {string} taskId The id of the task the event fired for
+   */
+  async completeActions(result, taskId) {
+    if (result === null) {
+      return;
+    }
+    const taskFolder = await this.getTaskFolderPath();
+    for (const target of result.targets) {
+      await this.saveTask(getTaskPath(taskFolder, target.task.id), target.task);
+    }
+    const boardAdds = [
+      ...result.patch.boardAdds.map((add) => ({ ...add, taskId })),
+      ...result.targets.flatMap((target) => target.boardAdds.map((add) => ({ ...add, taskId: target.task.id })))
+    ];
+    const thisBoardSlug = await this.resolveBoardSlug();
+    for (const add of boardAdds) {
+      const slug = await this.resolveBoardSlug(add.board);
+      if (slug === thisBoardSlug) {
+        continue;
+      }
+      if (!(await this.boardExists(slug))) {
+        this.lastActionWarnings.push(`skipped adding "${add.taskId}" to board "${add.board}": no such board`);
+        continue;
+      }
+      const otherBoard = this.board(slug);
+      const otherIndex = await otherBoard.loadIndex();
+      if (!(add.column in otherIndex.columns)) {
+        this.lastActionWarnings.push(
+          `skipped adding "${add.taskId}" to board "${add.board}": no column "${add.column}"`
+        );
+        continue;
+      }
+      if (taskInIndex(otherIndex, add.taskId)) {
+        continue;
+      }
+      await otherBoard.saveIndex(addTaskToIndex(otherIndex, add.taskId, add.column));
+    }
+  }
+
+  /**
+   * Work out which derived events an operation fired
+   *
+   * `task.started` and `task.completed` aren't operations - they're transitions, computed from the
+   * state before the operation and the state it is about to write, so a rule meaning "when this is
+   * done" doesn't have to duplicate the board's column list. They're computed before any rule runs,
+   * so a rule that sets a completed date doesn't fire task.completed
+   * @param {object} index The index object
+   * @param {?object} before The task as it was, or null if it didn't exist
+   * @param {object} after The task the operation is about to write
+   * @return {string[]} The derived event types that fired
+   */
+  derivedEvents(index, before, after) {
+    const events = [];
+    if (!taskStarted(index, { ...after, metadata: before === null ? {} : before.metadata }) && taskStarted(index, after)) {
+      events.push("task.started");
+    }
+    if (
+      !taskCompleted(index, { ...after, metadata: before === null ? {} : before.metadata }) &&
+      taskCompleted(index, after)
+    ) {
+      events.push("task.completed");
+    }
+    return events;
+  }
+
   /**
    * Check if a board exists
    * @param {string} slug The board slug
@@ -2593,15 +3574,37 @@ class Kanbn {
       column: columnName,
       fromProgress: 0,
       toProgress: getTaskMetadata(taskData, 'progress') || 0
-    }, await this.historyBoard());
+    }, await this.historyBoard(), await this.currentUser());
 
     // Update task metadata dates
+    const beforeActions = { ...taskData, metadata: {} };
     taskData = updateColumnLinkedCustomFields(index, taskData, columnName, now);
-    await this.saveTask(taskPath, taskData);
 
-    // Add the task to the index
+    // Add the task to the index before running rules, so that a rule filtering on the task's column
+    // sees the column it is being created in
     index = addTaskToIndex(index, taskId, columnName);
+
+    // Run actions and fold whatever they produce into the writes below
+    const result = await this.runActions({
+      eventTypes: ["task.created", ...this.derivedEvents(index, beforeActions, taskData)],
+      index,
+      taskId,
+      taskData,
+      payload: { column: columnName },
+      date: now
+    });
+    if (result !== null) {
+      ({ index, taskData } = result);
+      if (result.patch.moveTo !== null && result.patch.moveTo.column !== columnName) {
+        columnName = result.patch.moveTo.column;
+        index = removeTaskFromIndex(index, taskId);
+        index = addTaskToIndex(index, taskId, columnName, result.patch.moveTo.position);
+        taskData = updateColumnLinkedCustomFields(index, taskData, columnName, now);
+      }
+    }
+    await this.saveTask(taskPath, taskData);
     await this.saveIndex(index);
+    await this.completeActions(result, taskId);
     return taskId;
   }
 
@@ -2645,15 +3648,37 @@ class Kanbn {
       date: now,
       type: 'added',
       column: columnName
-    }, await this.historyBoard());
+    }, await this.historyBoard(), await this.currentUser());
 
     // Update task metadata dates
+    const beforeActions = { ...taskData, metadata: { ...taskData.metadata } };
     taskData = updateColumnLinkedCustomFields(index, taskData, columnName, now);
-    await this.saveTask(taskPath, taskData);
 
-    // Add the task to the column and save the index
+    // Add the task to the column before running rules, so that a rule filtering on the task's
+    // column sees the column it is joining
     index = addTaskToIndex(index, taskId, columnName);
+
+    // Run actions and fold whatever they produce into the writes below
+    const result = await this.runActions({
+      eventTypes: ["task.addedToBoard", ...this.derivedEvents(index, beforeActions, taskData)],
+      index,
+      taskId,
+      taskData,
+      payload: { column: columnName, board: await this.resolveBoardSlug() },
+      date: now
+    });
+    if (result !== null) {
+      ({ index, taskData } = result);
+      if (result.patch.moveTo !== null && result.patch.moveTo.column !== columnName) {
+        columnName = result.patch.moveTo.column;
+        index = removeTaskFromIndex(index, taskId);
+        index = addTaskToIndex(index, taskId, columnName, result.patch.moveTo.position);
+        taskData = updateColumnLinkedCustomFields(index, taskData, columnName, now);
+      }
+    }
+    await this.saveTask(taskPath, taskData);
     await this.saveIndex(index);
+    await this.completeActions(result, taskId);
     return taskId;
   }
 
@@ -2828,7 +3853,41 @@ class Kanbn {
         type: 'progress',
         fromProgress: originalProgress,
         toProgress: updatedProgress
-      });
+      }, null, await this.currentUser());
+    }
+
+    // Run actions. A task.updated rule that moves the task redirects the move this call was going
+    // to make, or makes one of its own if the caller didn't ask for a column change
+    const result = await this.runActions({
+      eventTypes: ["task.updated", ...this.derivedEvents(index, originalTaskData, taskData)],
+      index,
+      taskId,
+      taskData,
+      payload: { changedFields: changedFields(originalTaskData, taskData), unsetFields: [...unsetFields] },
+      date: now
+    });
+    let rulePosition = null;
+    if (result !== null) {
+      ({ index, taskData } = result);
+      if (result.patch.moveTo !== null) {
+        rulePosition = result.patch.moveTo.position;
+        if (columnName === null) {
+          const fromColumn = findTaskColumn(index, taskId);
+          if (fromColumn !== result.patch.moveTo.column) {
+            taskData = appendTaskHistory(
+              taskData,
+              { date: now, type: "moved", fromColumn, toColumn: result.patch.moveTo.column },
+              await this.historyBoard(),
+              result.patch.moveTo.author
+            );
+            index = removeTaskFromIndex(index, taskId);
+            index = addTaskToIndex(index, taskId, result.patch.moveTo.column, rulePosition);
+            taskData = updateColumnLinkedCustomFields(index, taskData, result.patch.moveTo.column, now);
+          }
+        } else {
+          columnName = result.patch.moveTo.column;
+        }
+      }
     }
 
     // Save task
@@ -2836,12 +3895,17 @@ class Kanbn {
 
     // Move the task if we're updating the column
     if (columnName) {
-      await this.moveTask(taskId, columnName);
+      // The move is a nested operation that fires its own rules, and reports its own skips. Keep
+      // this call's warnings in front of them rather than letting the move discard them
+      const updateWarnings = [...this.lastActionWarnings];
+      await this.moveTask(taskId, columnName, rulePosition);
+      this.lastActionWarnings = [...updateWarnings, ...this.lastActionWarnings];
 
       // Otherwise save the index
     } else {
       await this.saveIndex(index);
     }
+    await this.completeActions(result, taskId);
 
     // Remove any explicitly unset metadata fields last. This has to happen after the move, because
     // moving into a started or completed column stamps the linked date fields - an explicit unset
@@ -2990,12 +4054,12 @@ class Kanbn {
         type: 'moved',
         fromColumn: currentColumnName,
         toColumn: columnName
-      }, await this.historyBoard());
+      }, await this.historyBoard(), await this.currentUser());
     }
 
     // Update task metadata dates
+    const beforeActions = { ...taskData, metadata: { ...taskData.metadata } };
     taskData = updateColumnLinkedCustomFields(index, taskData, columnName, moveDate);
-    await this.saveTask(getTaskPath(await this.getTaskFolderPath(), taskId), taskData);
 
     // If we're moving the task to a new position, calculate the absolute position
     const currentPosition = index.columns[currentColumnName].indexOf(taskId);
@@ -3009,7 +4073,39 @@ class Kanbn {
     // Remove the task from its current column and add it to the new column
     index = removeTaskFromIndex(index, taskId);
     index = addTaskToIndex(index, taskId, columnName, position);
+
+    // Run actions. A rule that moves the task changes the destination of the write that was already
+    // about to happen, rather than performing a second move
+    const eventTypes = this.derivedEvents(index, beforeActions, taskData);
+    if (currentColumnName !== columnName) {
+      eventTypes.unshift("task.moved");
+    }
+    const result = await this.runActions({
+      eventTypes,
+      index,
+      taskId,
+      taskData,
+      payload: { fromColumn: currentColumnName, toColumn: columnName },
+      date: moveDate
+    });
+    if (result !== null) {
+      ({ index, taskData } = result);
+      if (result.patch.moveTo !== null && result.patch.moveTo.column !== columnName) {
+        const ruleColumn = result.patch.moveTo.column;
+        taskData = appendTaskHistory(
+          taskData,
+          { date: moveDate, type: "moved", fromColumn: columnName, toColumn: ruleColumn },
+          await this.historyBoard(),
+          result.patch.moveTo.author
+        );
+        index = removeTaskFromIndex(index, taskId);
+        index = addTaskToIndex(index, taskId, ruleColumn, result.patch.moveTo.position);
+        taskData = updateColumnLinkedCustomFields(index, taskData, ruleColumn, moveDate);
+      }
+    }
+    await this.saveTask(getTaskPath(await this.getTaskFolderPath(), taskId), taskData);
     await this.saveIndex(index);
+    await this.completeActions(result, taskId);
     return taskId;
   }
 
@@ -3044,8 +4140,30 @@ class Kanbn {
       );
     }
 
-    // Remove the task from whichever column it's in
+    // Run actions before anything is removed, so that a rule's targets are selected from the task's
+    // relations while the task is still there to have them
     const columnName = findTaskColumn(index, taskId);
+    const taskFileExists = await exists(getTaskPath(await this.getTaskFolderPath(), taskId));
+    let result = null;
+    if (taskFileExists) {
+      result = await this.runActions({
+        eventTypes: ["task.deleted"],
+        index,
+        taskId,
+        taskData: await this.loadTask(taskId),
+        payload: { fromColumn: columnName, removeFile, allBoards },
+
+        // Removing a task from one board isn't a workspace-wide operation, whatever the event is
+        // called, so the other boards' rules have nothing to hear about
+        taskBoards: allBoards ? null : false,
+        date: new Date()
+      });
+      if (result !== null) {
+        index = result.index;
+      }
+    }
+
+    // Remove the task from whichever column it's in
     index = removeTaskFromIndex(index, taskId);
 
     // Record the task leaving this board, but only when the task file survives - a removed event on
@@ -3055,7 +4173,7 @@ class Kanbn {
       taskData = appendTaskHistory(taskData, {
         type: 'removed',
         fromColumn: columnName
-      }, await this.historyBoard());
+      }, await this.historyBoard(), await this.currentUser());
       await this.saveTask(getTaskPath(await this.getTaskFolderPath(), taskId), taskData);
     }
 
@@ -3071,6 +4189,7 @@ class Kanbn {
       await fs.promises.unlink(getTaskPath(await this.getTaskFolderPath(), taskId));
     }
     await this.saveIndex(index);
+    await this.completeActions(result, taskId);
     return taskId;
   }
 
@@ -3307,7 +4426,7 @@ class Kanbn {
           start: sprints[sprintIndex].start,
         };
         if (currentSprint - 1 !== sprintIndex) {
-          if (sprintIndex === sprints.length - 1) {
+          if (sprintIndex !== sprints.length - 1) {
             result.sprint.end = sprints[sprintIndex + 1].start;
           }
           result.sprint.current = currentSprint;
@@ -3413,6 +4532,25 @@ class Kanbn {
       return errors;
     }
 
+    // Action rules are configuration: a rule that names an unknown event or verb is wrong in the
+    // file, and an operation that meets one fails before writing anything, so it belongs here
+    // rather than in the warnings
+    try {
+      const rules = await this.getActionRules(index);
+      const context = { columns: Object.keys(index.columns) };
+      if (await this.workspaceInitialised()) {
+        context.boards = (await this.listBoards()).map((board) => board.slug);
+      }
+      for (const error of actions.findRuleErrors(rules, context)) {
+        errors.push({ task: null, errors: `actions: ${error}` });
+      }
+    } catch (error) {
+      errors.push({ task: null, errors: `actions: ${error.message}` });
+    }
+    if (errors.length) {
+      return errors;
+    }
+
     // Load & parse tasks
     const trackedTasks = getTrackedTaskIds(index);
     for (let taskId of trackedTasks) {
@@ -3628,6 +4766,160 @@ class Kanbn {
     return warnings;
   }
 
+  /**
+   * Collect every distinct value used in an `assigned` field or a comment `author` across the
+   * workspace's task files, along with where each one is used
+   *
+   * Tasks are workspace-scoped - a task file can be referenced by several boards - so this reads the
+   * task folder rather than any one board. Task files that don't parse are skipped: this is a
+   * reporting helper, and `kanbn validate` is where a broken file gets reported
+   * @return {Promise<Map<string, object>>} A map of value to usage entry
+   */
+  async collectContributorValues() {
+    if (!(await this.workspaceInitialised())) {
+      throw new Error("Not initialised in this folder");
+    }
+    const values = new Map();
+    const record = (value, taskId, field) => {
+      if (typeof value !== "string" || !value.trim()) {
+        return;
+      }
+      const key = value.trim();
+      if (!values.has(key)) {
+        values.set(key, { value: key, assigned: 0, comments: 0, tasks: new Set() });
+      }
+      const entry = values.get(key);
+      entry[field]++;
+      entry.tasks.add(taskId);
+    };
+    for (const taskPath of await glob(`${await this.getTaskFolderPath()}/*.md`)) {
+      const taskId = path.parse(taskPath).name;
+      let taskData = null;
+      try {
+        taskData = await this.loadTask(taskId);
+      } catch (error) {
+        continue;
+      }
+      record(getTaskMetadata(taskData, "assigned"), taskId, "assigned");
+      for (const comment of taskData.comments || []) {
+        record(comment.author, taskId, "comments");
+      }
+    }
+    return values;
+  }
+
+  /**
+   * Report how the workspace's contributors are actually used, and which names are in use that the
+   * contributors list doesn't know about
+   *
+   * The second half is the point: adopting contributors in a workspace with 200 existing tasks
+   * otherwise means grepping. This is read-only - rewriting "Gordon" to "gordon" across every task
+   * file is a bulk mutation and belongs to its own command, with its own dry run
+   * @return {Promise<{contributors: object[], unknown: object[]}>} Usage per known contributor, and
+   * every value in use that isn't one
+   */
+  async getContributorUsage() {
+    const contributors = await this.getContributors();
+    const values = await this.collectContributorValues();
+    const usage = contributors.map((contributor) => ({
+      ...contributor,
+      assigned: 0,
+      comments: 0,
+      tasks: new Set(),
+      spellings: []
+    }));
+    const unknown = [];
+    for (const entry of [...values.values()].sort((a, b) => a.value.localeCompare(b.value))) {
+      const result = {
+        value: entry.value,
+        assigned: entry.assigned,
+        comments: entry.comments,
+        tasks: [...entry.tasks].sort()
+      };
+      const contributor = matchContributor(contributors, entry.value);
+      if (contributor === null) {
+        unknown.push(result);
+        continue;
+      }
+      const target = usage.find((u) => u.name === contributor.name);
+      target.assigned += entry.assigned;
+      target.comments += entry.comments;
+
+      // Counted as a set, so a task naming the same person twice under two spellings is one task
+      for (const taskId of entry.tasks) {
+        target.tasks.add(taskId);
+      }
+      target.spellings.push(result);
+    }
+    return {
+      contributors: usage.map((contributor) => ({ ...contributor, tasks: contributor.tasks.size })),
+      unknown
+    };
+  }
+
+  /**
+   * Find things about this board's action rules that are legal but probably not what the author meant
+   *
+   * Rules that are wrong in the file are errors, reported by validate(). These are the ones that
+   * work: two rules writing the same field on the same event, or a rule using @me where no user can
+   * be resolved
+   * @return {Promise<object[]>} A list of warnings
+   */
+  async findActionWarnings() {
+    if (!(await this.initialised())) {
+      throw new Error("Not initialised in this folder");
+    }
+    let rules = [];
+    try {
+      rules = await this.getActionRules();
+    } catch (error) {
+      // A rule set that can't be read is an error rather than a warning, and validate reports it
+      return [];
+    }
+    if (!rules.length) {
+      return [];
+    }
+    return actions.findRuleWarnings(rules, { hasUser: (await this.currentUser()) !== null });
+  }
+
+  /**
+   * Find tasks whose assigned user or comment author isn't a known contributor
+   *
+   * Contributors are advisory, so this is a warning and never an error: `assigned` and `author` stay
+   * free text, and a name that isn't in the list is written, read and filtered exactly as before.
+   * Nothing is reported at all when the workspace declares no contributors
+   * @return {Promise<object[]>} A list of warnings
+   */
+  async findContributorWarnings() {
+    const contributors = await this.getContributors();
+    if (!contributors.length) {
+      return [];
+    }
+    const warnings = [];
+    for (const entry of [...(await this.collectContributorValues()).values()].sort((a, b) =>
+      a.value.localeCompare(b.value)
+    )) {
+      if (matchContributor(contributors, entry.value) !== null) {
+        continue;
+      }
+
+      // A comment written by a rule is authored by the rule, not by a person, so it is never a
+      // missing contributor
+      if (entry.value === actions.ACTION_AUTHOR_PREFIX || entry.value.startsWith(`${actions.ACTION_AUTHOR_PREFIX}/`)) {
+        continue;
+      }
+      for (const taskId of [...entry.tasks].sort()) {
+        warnings.push({
+          task: taskId,
+          type: "unknown-contributor",
+          value: entry.value,
+          message: `"${entry.value}" isn't a known contributor`
+        });
+      }
+    }
+    return warnings;
+  }
+
   /**
    * Find tasks whose started/completed dates disagree with the column they're in
    *
@@ -4245,7 +5537,7 @@ class Kanbn {
    * @param {string} author The comment author
    * @return {Promise<string>} The task id
    */
-  async comment(taskId, text, author) {
+  async comment(taskId, text, author = "") {
     // Check if this folder has been initialised
     if (!(await this.initialised())) {
       throw new Error("Not initialised in this folder");
@@ -4269,16 +5561,54 @@ class Kanbn {
     }
 
     // Add the comment
-    const taskData = await this.loadTask(taskId);
+    let taskData = await this.loadTask(taskId);
     const taskPath = getTaskPath(await this.getTaskFolderPath(), taskId);
+    const now = new Date();
     taskData.comments.push({
       text,
-      author,
-      date: new Date(),
+
+      // An author is optional, and a machine with no resolvable user has none. Serialising null
+      // fails schema validation, so the task could never be written back
+      author: author || "",
+      date: now,
+    });
+
+    // Run actions
+    const result = await this.runActions({
+      eventTypes: ["task.commented"],
+      index,
+      taskId,
+      taskData,
+      payload: { comment: text },
+      date: now
     });
+    if (result !== null) {
+      ({ taskData } = result);
+      index = result.index;
+      if (result.patch.moveTo !== null) {
+        const fromColumn = findTaskColumn(index, taskId);
+        if (fromColumn !== result.patch.moveTo.column) {
+          taskData = appendTaskHistory(
+            taskData,
+            { date: now, type: "moved", fromColumn, toColumn: result.patch.moveTo.column },
+            await this.historyBoard(),
+            result.patch.moveTo.author
+          );
+          index = removeTaskFromIndex(index, taskId);
+          index = addTaskToIndex(index, taskId, result.patch.moveTo.column, result.patch.moveTo.position);
+          taskData = updateColumnLinkedCustomFields(index, taskData, result.patch.moveTo.column, now);
+        }
+      }
+    }
 
     // Save the task
     await this.saveTask(taskPath, taskData);
+
+    // Commenting doesn't touch the index, so it is only written when a rule moved something
+    if (result !== null && (result.patch.moveTo !== null || result.targets.some((target) => target.moveTo !== null))) {
+      await this.saveIndex(index);
+    }
+    await this.completeActions(result, taskId);
     return taskId;
   }
 
@@ -4352,16 +5682,35 @@ class Kanbn {
     }
 
     // Add history event. Archiving isn't board-scoped, so the event carries no board key
+    const now = new Date();
     taskData = appendTaskHistory(taskData, {
       type: 'archived',
       fromColumn: taskColumn
+    }, null, await this.currentUser());
+
+    // Run actions
+    const result = await this.runActions({
+      eventTypes: ["task.archived"],
+      index,
+      taskId,
+      taskData,
+      payload: { fromColumn: taskColumn },
+      date: now
     });
+    if (result !== null) {
+      ({ index, taskData } = result);
+      if (result.targets.some((target) => target.moveTo !== null)) {
+        await this.saveIndex(index);
+      }
+    }
 
     // Save the task inside the archive folder
     await this.saveTask(archivedTaskPath, taskData);
+    await this.completeActions(result, taskId);
 
-    // Remove the original task from every board that references it
-    await this.deleteTask(taskId, true, true);
+    // Remove the original task from every board that references it. This removal is part of the
+    // archive rather than a deletion anyone wrote a rule for, so it fires nothing
+    await this.withoutActions().deleteTask(taskId, true, true);
 
     return taskId;
   }
@@ -4449,15 +5798,40 @@ class Kanbn {
       date: now,
       type: 'restored',
       toColumn: actualColumnName
-    });
+    }, null, await this.currentUser());
 
-    // Update task metadata dates and save task
+    // Update task metadata dates
+    const beforeActions = { ...taskData, metadata: { ...taskData.metadata } };
     taskData = updateColumnLinkedCustomFields(index, taskData, actualColumnName, now);
-    await this.saveTask(taskPath, taskData);
 
-    // Add the task to the column and save the index
+    // Add the task to the column before running rules, so that a rule filtering on the task's
+    // column sees the column it is being restored to
     index = addTaskToIndex(index, taskId, actualColumnName);
+
+    // Run actions
+    const result = await this.runActions({
+      eventTypes: ["task.restored", ...this.derivedEvents(index, beforeActions, taskData)],
+      index,
+      taskId,
+      taskData,
+      payload: { toColumn: actualColumnName },
+
+      // The task isn't on any board yet, so the index can't say which boards this affects
+      taskBoards: [thisBoardSlug, ...otherBoards.map(([slug]) => slug)],
+      date: now
+    });
+    if (result !== null) {
+      ({ index, taskData } = result);
+      if (result.patch.moveTo !== null && result.patch.moveTo.column !== actualColumnName) {
+        actualColumnName = result.patch.moveTo.column;
+        index = removeTaskFromIndex(index, taskId);
+        index = addTaskToIndex(index, taskId, actualColumnName, result.patch.moveTo.position);
+        taskData = updateColumnLinkedCustomFields(index, taskData, actualColumnName, now);
+      }
+    }
+    await this.saveTask(taskPath, taskData);
     await this.saveIndex(index);
+    await this.completeActions(result, taskId);
 
     // Restore the task to every other board it was on, falling back to that board's first column if
     // the column it used to be in has since gone