@nickmeriano/task 0.7.1 → 0.9.0

package/dist/cli.js

@@ -1,32 +1,29 @@
 #!/usr/bin/env node
 // The `task` CLI — tasks that live in your repo. Zero dependencies: hand-rolled
-// flag parsing, plain-text tickets in .task/tickets/ for storage (node:sqlite
-// still reads boards from before `task migrate`), plain text out (--json for
-// agents).
+// flag parsing, plain-text tickets in .task/tickets/ for storage, plain text
+// out (--json for agents).
 //
 //   task init
-//   task add "Wire up webhooks" --tags api,infra --milestone launch
+//   task add "Wire up webhooks" --tags api,infra --goal launch
 //   task list --status todo,in_progress
-//   task start TAS-3 && task done TAS-3
+//   task move TAS-x7k4m done
 //   task serve
 import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import { basename, join, relative, sep } from "node:path";
 import process from "node:process";
 import { resolveAuthor } from "./author.js";
-import { ClaimError, claim, claimableTasks, release } from "./claim.js";
+import { checkBoards, checkRoot } from "./check.js";
+import { ClaimError, claim, claimNext, claimableTasks, promote, release, selectionBoards, } from "./claim.js";
+import { addAskRouted, setAskResolvedRouted } from "./claim-io.js";
+import { buildInbox } from "./inbox.js";
+import { STALE_DAYS, buildOverview } from "./overview.js";
+import { searchStore } from "./search.js";
 import { detectRepo, parseSlug, publish, resolveHost } from "./publish.js";
 import { createTaskServer } from "./server.js";
-import { initProject, migrateBoard, openBoard } from "./file-store.js";
+import { initProject, openBoard } from "./file-store.js";
 import { CONFIG_FILE, TASK_DIR, boardConfig, findBoards, findBoardsByPrefix, findRoot, findScopeRoot, } from "./store.js";
 import { STATUSES, isStatus } from "./types.js";
-// node:sqlite still emits an ExperimentalWarning on Node 22 — noise in a CLI
-// that runs it on every invocation. Filter that one warning, keep the rest.
-process.removeAllListeners("warning");
-process.on("warning", (warning) => {
-    if (warning.name !== "ExperimentalWarning")
-        console.error(warning);
-});
 /**
  * Read from package.json rather than duplicated as a literal. Releases here are
  * cut by changesets, which bumps package.json and nothing else — so a hardcoded
@@ -50,7 +47,6 @@ const BOOLEAN_FLAGS = new Set([
     "version",
     "yes",
     "needs-human",
-    "no-needs-human",
     "archived",
     "claimable",
     "release",
@@ -60,30 +56,57 @@ const BOOLEAN_FLAGS = new Set([
     "public",
     "private",
     "no-wait",
+    "fix",
+    "next",
+    "force",
+    "reopen",
 ]);
+/**
+ * Value flags that may repeat — `--board NIC --board TAS` accumulates in
+ * given order, equivalent to `--board NIC,TAS`. Everything else keeps
+ * last-one-wins.
+ */
+const REPEATABLE_FLAGS = new Set(["board"]);
+/**
+ * Repeatable flags whose values are free text — collected verbatim into a
+ * list, never comma-joined, because an ask like "check A, then B" must
+ * survive as one ask.
+ */
+const MULTI_FLAGS = new Set(["ask"]);
 function parseArgs(argv) {
     const positional = [];
     const flags = {};
+    const multi = {};
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg.startsWith("--")) {
             const name = arg.slice(2);
+            const set = (key, value) => {
+                if (MULTI_FLAGS.has(key)) {
+                    ;
+                    (multi[key] ??= []).push(value);
+                    return;
+                }
+                const prior = flags[key];
+                flags[key] =
+                    REPEATABLE_FLAGS.has(key) && typeof prior === "string" ? `${prior},${value}` : value;
+            };
             const eq = name.indexOf("=");
             if (eq >= 0) {
-                flags[name.slice(0, eq)] = name.slice(eq + 1);
+                set(name.slice(0, eq), name.slice(eq + 1));
             }
             else if (BOOLEAN_FLAGS.has(name) || i + 1 >= argv.length || argv[i + 1].startsWith("--")) {
                 flags[name] = true;
             }
             else {
-                flags[name] = argv[++i];
+                set(name, argv[++i]);
             }
         }
         else {
             positional.push(arg);
         }
     }
-    return { positional, flags };
+    return { positional, flags, multi };
 }
 function str(flags, name) {
     const v = flags[name];
@@ -99,18 +122,18 @@ function openStore() {
         fail("no .task directory found in this directory or any parent — run `task init` first");
     return openBoard(root);
 }
-/** The prefix a ref carries, if any: "TAS-12" → "TAS", "12" → null. */
+/** The prefix a ref carries, if any: "TAS-x7k4m" → "TAS", "x7k4m" → null. */
 function refPrefix(ref) {
-    const match = /^([A-Za-z0-9]+)-\d+$/.exec(ref.trim());
+    const match = /^([A-Za-z0-9]+)-[A-Za-z0-9]+$/.exec(ref.trim());
     return match ? match[1].toUpperCase() : null;
 }
 /**
- * The board a ref belongs to. A bare number means the nearest board, as ever —
+ * The board a ref belongs to. A bare key means the nearest board, as ever —
  * but a prefixed id is an address, and it routes: if the prefix isn't the
  * nearest board's, every board in the repo (walking up to the outermost board
- * root, then down) is searched for it, so `task show TAS-12` works from
+ * root, then down) is searched for it, so `task show TAS-x7k4m` works from
  * anywhere in a monorepo. What this must never do is what it used to: silently
- * strip a foreign prefix and act on the nearest board's ticket of that number.
+ * strip a foreign prefix and act on the nearest board's ticket of that key.
  */
 function openStoreFor(ref) {
     const prefix = ref ? refPrefix(ref) : null;
@@ -170,21 +193,32 @@ function patchFromFlags(flags) {
     if (title !== undefined)
         patch.title = title;
     const description = str(flags, "description") ?? str(flags, "desc");
+    // Long markdown doesn't survive shell quoting — `--description-file` keeps
+    // agents writing plans and specs on the CLI path instead of hand-editing
+    // ticket files. `-` reads stdin.
+    const descriptionFile = str(flags, "description-file");
+    if (description !== undefined && descriptionFile !== undefined) {
+        fail("pass --description or --description-file, not both");
+    }
     if (description !== undefined)
         patch.description = description;
+    if (descriptionFile !== undefined) {
+        try {
+            patch.description = readFileSync(descriptionFile === "-" ? 0 : descriptionFile, "utf8");
+        }
+        catch {
+            fail(`--description-file: can't read ${descriptionFile === "-" ? "stdin" : descriptionFile}`);
+        }
+    }
     const status = str(flags, "status");
     if (status !== undefined)
         patch.status = parseStatus(status);
     const tags = str(flags, "tags") ?? str(flags, "tag");
     if (tags !== undefined)
         patch.tags = parseTags(tags);
-    const milestone = str(flags, "milestone");
-    if (milestone !== undefined)
-        patch.milestone = milestone.trim() || null;
-    if (flags["needs-human"])
-        patch.needsHuman = true;
-    if (flags["no-needs-human"])
-        patch.needsHuman = false;
+    const goal = str(flags, "goal");
+    if (goal !== undefined)
+        patch.goal = goal.trim() || null;
     // Replace semantics like --tags; `--pr` (append one) is handled per-command
     // because appending needs the task's current list.
     const prs = str(flags, "prs");
@@ -216,7 +250,7 @@ function taskRow(t) {
         t.needsHuman ? "⚑" : "",
         t.title,
         t.tags.join(","),
-        t.milestone ?? "",
+        t.goal ?? "",
     ];
 }
 function printTask(t) {
@@ -244,22 +278,40 @@ function cmdInit(args) {
 function cmdAdd(args) {
     const title = args.positional.join(" ").trim();
     if (!title)
-        fail(`usage: task add <title> [--description …] [--status …] [--tags a,b] [--milestone …] [--needs-human]`);
+        fail(`usage: task add <title> [--description …] [--status …] [--tags a,b] [--goal <slug>] [--ask "<text>"]…`);
     const store = openStore();
     const patch = patchFromFlags(args.flags);
     const pr = str(args.flags, "pr");
     if (pr)
         patch.prs = [...(patch.prs ?? []), pr];
-    const task = store.create({ title, ...patch });
+    let task = store.create({ title, ...patch });
+    const asks = (args.multi.ask ?? []).map((a) => a.trim()).filter(Boolean);
+    if (asks.length > 0) {
+        const author = resolveAuthor(str(args.flags, "author")).name;
+        for (const text of asks)
+            store.addAsk(task.key, text, author);
+        task = store.get(task.key);
+    }
     if (args.flags.json) {
         console.log(JSON.stringify({ task }, null, 2));
     }
     else {
         printTask(task);
+        for (const ask of task.asks)
+            console.log(`  ask [${ask.ordinal}] ${ask.text.split("\n")[0]}`);
     }
 }
+/** `--board NIC --board TAS` (or `--board NIC,TAS`) → ["NIC", "TAS"]. */
+function boardFlag(args) {
+    const raw = str(args.flags, "board");
+    if (raw === undefined)
+        return undefined;
+    const prefixes = raw.split(",").map((p) => p.trim()).filter(Boolean);
+    if (prefixes.length === 0)
+        fail("--board needs a prefix, e.g. --board TAS");
+    return prefixes;
+}
 function cmdList(args) {
-    const store = openStore();
     if (args.flags.claimable) {
         // The dispatcher's queue view (TAS-21): claimable already pins the status
         // set and consults origin, so the board-shaping flags don't compose.
@@ -267,7 +319,17 @@ function cmdList(args) {
             if (args.flags[flag] !== undefined)
                 fail(`--claimable can't be combined with --${flag}`);
         }
-        const tasks = claimableTasks(store);
+        // Selection scope, same resolution as `claim --next`: --board flag > root
+        // board's `boards` list > nearest board. Board order is priority order.
+        let tasks;
+        try {
+            tasks = selectionBoards(process.cwd(), boardFlag(args)).flatMap((s) => claimableTasks(s));
+        }
+        catch (error) {
+            if (error instanceof ClaimError)
+                fail(error.message);
+            throw error;
+        }
         if (args.flags.json) {
             console.log(JSON.stringify({ tasks }, null, 2));
         }
@@ -279,6 +341,9 @@ function cmdList(args) {
         }
         return;
     }
+    if (args.flags.board !== undefined)
+        fail("--board only applies to list --claimable");
+    const store = openStore();
     const archived = Boolean(args.flags.archived);
     const statusFlag = str(args.flags, "status");
     const statuses = statusFlag
@@ -292,7 +357,7 @@ function cmdList(args) {
     const tasks = store.list({
         statuses,
         tags: tagFlag ? parseTags(tagFlag) : undefined,
-        milestone: str(args.flags, "milestone"),
+        goal: str(args.flags, "goal"),
         needsHuman: args.flags["needs-human"] ? true : undefined,
         archived: archived || undefined,
     });
@@ -313,6 +378,43 @@ function cmdList(args) {
         table(tasks.map(taskRow));
     }
 }
+/**
+ * `task search <query>` — find tickets by what they say. Case-insensitive
+ * substring over titles, descriptions and comments, scoped by the usual list
+ * filters; `--archived` searches the archive *in addition to* the board (a
+ * search is a question about everything ever written down, unlike
+ * `list --archived`, which is a view of one place).
+ */
+function cmdSearch(args) {
+    const query = args.positional.join(" ").trim();
+    if (!query) {
+        fail("usage: task search <query> [--status <s1,s2>] [--tag <a,b>] [--goal <slug>] [--needs-human] [--archived]");
+    }
+    const store = openStore();
+    const statusFlag = str(args.flags, "status");
+    const tagFlag = str(args.flags, "tags") ?? str(args.flags, "tag");
+    const results = searchStore(store, query, {
+        statuses: statusFlag ? statusFlag.split(",").map(parseStatus) : undefined,
+        tags: tagFlag ? parseTags(tagFlag) : undefined,
+        goal: str(args.flags, "goal"),
+        needsHuman: args.flags["needs-human"] ? true : undefined,
+    }, Boolean(args.flags.archived));
+    if (args.flags.json) {
+        console.log(JSON.stringify({ query, results }, null, 2));
+        return;
+    }
+    if (results.length === 0) {
+        console.log(`no matches for "${query}"${args.flags.archived ? "" : " (--archived searches the archive too)"}`);
+        return;
+    }
+    for (const { task, matches } of results) {
+        console.log(`${task.id}  ${STATUS_GLYPH[task.status]} ${task.status}${task.archived ? " (archived)" : ""}  ${task.title}`);
+        for (const match of matches) {
+            const label = match.field === "comment" ? `comment${match.author ? ` by ${match.author}` : ""}` : match.field;
+            console.log(`        ${label}: ${match.snippet}`);
+        }
+    }
+}
 /**
  * `task boards` — every board in this repo, found the way `task serve` finds
  * them but anchored at the *outermost* board root, so it answers from anywhere
@@ -377,7 +479,7 @@ function cmdArchive(args) {
     }
     const store = openStore();
     const finished = store.list({ statuses: ["done", "canceled"] });
-    const archived = finished.map((t) => store.archive(t.number));
+    const archived = finished.map((t) => store.archive(t.key));
     if (args.flags.json) {
         console.log(JSON.stringify({ archived }, null, 2));
     }
@@ -407,32 +509,46 @@ function cmdShow(args) {
     if (!ref)
         fail("usage: task show <id>");
     const store = openStoreFor(ref);
-    const number = store.parseId(ref);
-    const task = store.get(number);
+    const key = store.parseId(ref);
+    const task = store.get(key);
     if (!task)
-        fail(`no such task: ${store.displayId(number)}`);
-    const comments = store.comments(number);
+        fail(`no such task: ${store.displayId(key)}`);
+    const comments = store.comments(key);
+    // The goal rides along in full — title *and* description — so an agent
+    // picking the ticket up cold inherits the shared context without it being
+    // pasted into every ticket. null when unset or when the ref dangles.
+    const goal = task.goal ? store.getGoal(task.goal) : null;
     if (args.flags.json) {
-        console.log(JSON.stringify({ task, comments }, null, 2));
+        console.log(JSON.stringify({ task, comments, goal }, null, 2));
         return;
     }
     // A linked task is only as useful as knowing whether it's still in the way.
-    const describeLinks = (numbers) => numbers
-        .map((n) => {
-        const other = store.get(n);
-        return other ? `${other.id} (${other.status})` : store.displayId(n);
+    const describeLinks = (keys) => keys
+        .map((k) => {
+        const other = store.get(k);
+        return other ? `${other.id} (${other.status})` : store.displayId(k);
     })
         .join(", ");
     console.log(`${task.id}  ${task.title}`);
     console.log(`status    ${task.status}`);
     if (task.archived)
         console.log(`archived  yes — \`task unarchive ${task.id}\` to edit`);
-    if (task.needsHuman)
-        console.log(`needs     a human`);
+    const openAsks = task.asks.filter((a) => !a.resolvedAt);
+    if (openAsks.length) {
+        console.log(`needs     a human — ${openAsks.length} open ask${openAsks.length === 1 ? "" : "s"}`);
+    }
+    for (const ask of task.asks) {
+        const state = ask.resolvedAt
+            ? `✓ resolved${ask.resolvedBy ? ` by ${ask.resolvedBy}` : ""}`
+            : `○ open${ask.author ? ` · ${ask.author}` : ""} · ${ask.createdAt.slice(0, 10)}`;
+        console.log(`ask [${ask.ordinal}]   ${ask.text.split("\n").join("\n          ")}`);
+        console.log(`          ${state}`);
+    }
     if (task.tags.length)
         console.log(`tags      ${task.tags.join(", ")}`);
-    if (task.milestone)
-        console.log(`milestone ${task.milestone}`);
+    if (task.goal) {
+        console.log(`goal      ${task.goal}${goal ? ` — ${goal.title}${goal.archived ? " (archived)" : ""}` : ""}`);
+    }
     if (task.blockedBy.length)
         console.log(`blocked   by ${describeLinks(task.blockedBy)}`);
     if (task.blocks.length)
@@ -443,6 +559,10 @@ function cmdShow(args) {
     console.log(`updated   ${task.updatedAt}`);
     if (task.description)
         console.log(`\n${task.description}`);
+    if (goal?.description) {
+        console.log(`\n── goal: ${goal.title} (${goal.slug})`);
+        console.log(goal.description.split("\n").map((line) => `  ${line}`).join("\n"));
+    }
     if (comments.length) {
         console.log(``);
         for (const c of comments) {
@@ -451,24 +571,22 @@ function cmdShow(args) {
         }
     }
 }
-function cmdUpdate(args, forcedStatus) {
+function cmdUpdate(args) {
     const ref = args.positional[0];
     if (!ref)
         fail("usage: task update <id> [--status …] [--title …] …");
     const store = openStoreFor(ref);
-    const number = store.parseId(ref);
+    const key = store.parseId(ref);
     const patch = patchFromFlags(args.flags);
-    if (forcedStatus)
-        patch.status = forcedStatus;
     const pr = str(args.flags, "pr");
     if (pr) {
         // Append, dedup — `--pr <url>` is "attach this PR", not "replace the list".
-        const current = patch.prs ?? store.get(number)?.prs ?? [];
+        const current = patch.prs ?? store.get(key)?.prs ?? [];
         patch.prs = current.includes(pr) ? current : [...current, pr];
     }
     if (Object.keys(patch).length === 0)
         fail("nothing to update — pass at least one flag");
-    const task = store.update(number, patch);
+    const task = store.update(key, patch);
     if (args.flags.json) {
         console.log(JSON.stringify({ task }, null, 2));
     }
@@ -480,7 +598,152 @@ function cmdMove(args) {
     const [ref, status] = args.positional;
     if (!ref || !status)
         fail("usage: task move <id> <status>");
-    cmdUpdate({ positional: [ref], flags: { ...args.flags, status } });
+    cmdUpdate({ positional: [ref], flags: { ...args.flags, status }, multi: {} });
+}
+/**
+ * `task promote <id>` — backlog → todo, the human "build this" call; see
+ * claim.ts for why blocked / needs-human are holds (reported), not refusals.
+ * Exit codes follow claim's contract: 0 promoted, 2 refused (fix something).
+ */
+function cmdPromote(args) {
+    const ref = args.positional[0];
+    if (!ref)
+        fail("usage: task promote <id>");
+    const store = openStoreFor(ref);
+    try {
+        const result = promote(store, store.parseId(ref));
+        if (args.flags.json) {
+            console.log(JSON.stringify({ task: result.task, holds: result.holds }, null, 2));
+        }
+        else {
+            printTask(result.task);
+            for (const hold of result.holds) {
+                console.log(`note: ${hold} — in todo, but not claimable until that clears`);
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof ClaimError) {
+            console.error(`error: ${error.message}`);
+            process.exit(2);
+        }
+        throw error;
+    }
+}
+/**
+ * `task ask <id> <text>` — file one thing a person owes this ticket. The ask
+ * is the primitive every human requirement funnels through: it derives the
+ * needs-human badge, feeds `task inbox`, and gates `done` until resolved.
+ * On a claimed ticket the write lands on the claim branch as a pushed commit
+ * (see claim-io.ts) — the worker's done gate has to see debt filed mid-claim.
+ */
+function cmdAsk(args) {
+    const [ref, ...rest] = args.positional;
+    const text = rest.join(" ").trim();
+    if (!ref || !text)
+        fail(`usage: task ask <id> "<what a person needs to do>" [--author <who>]`);
+    const store = openStoreFor(ref);
+    const author = resolveAuthor(str(args.flags, "author")).name;
+    const { ask, branch } = addAskRouted(store, store.parseId(ref), text, author);
+    if (args.flags.json) {
+        console.log(JSON.stringify({ ask, branch }, null, 2));
+    }
+    else {
+        console.log(`asked on ${ask.taskId} [${ask.ordinal}]  ${ask.text.split("\n")[0]}`);
+        if (branch)
+            console.log(`committed and pushed to ${branch} — the claim owns this ticket's asks`);
+    }
+}
+/**
+ * `task resolve <id> <n>` — check an ask off (`--reopen` puts it back). The
+ * ordinal is the one `task show` prints; the optional --comment lands as an
+ * attributed comment so the answer travels with the ticket, not just the
+ * checkbox. Resolving the last open ask is the moment a ticket usually moves
+ * to done — the hint below says so rather than doing it, because finishing a
+ * ticket is a statement about the *work*, not the asks.
+ */
+function cmdResolve(args) {
+    const [ref, askRef] = args.positional;
+    if (!ref || !askRef) {
+        fail('usage: task resolve <id> <ordinal> [--comment "<note>"] [--reopen] [--author <who>]');
+    }
+    const store = openStoreFor(ref);
+    const key = store.parseId(ref);
+    const author = resolveAuthor(str(args.flags, "author")).name;
+    const { ask, branch } = setAskResolvedRouted(store, key, askRef, !args.flags.reopen, author);
+    const note = str(args.flags, "comment")?.trim();
+    const comment = note
+        ? store.addComment(key, `${args.flags.reopen ? "Reopened" : "Resolved"} ask [${ask.ordinal}] (${ask.text.split("\n")[0]}): ${note}`, author)
+        : null;
+    const task = store.get(key);
+    // Branch-resolved asks aren't in the local files — count what's still open
+    // on the side that was just written.
+    const remaining = branch
+        ? undefined
+        : task.asks.filter((a) => !a.resolvedAt).length;
+    if (args.flags.json) {
+        console.log(JSON.stringify({ ask, branch, comment, openAsks: remaining ?? null }, null, 2));
+        return;
+    }
+    const verb = args.flags.reopen ? "reopened" : "resolved";
+    console.log(`${verb} ${ask.taskId} [${ask.ordinal}]  ${ask.text.split("\n")[0]}`);
+    if (branch) {
+        console.log(`committed and pushed to ${branch} — the worker sees it on its next pull`);
+        return;
+    }
+    if (args.flags.reopen)
+        return;
+    if (remaining !== undefined && remaining > 0) {
+        console.log(`${remaining} ask${remaining === 1 ? "" : "s"} still open on ${ask.taskId}`);
+    }
+    else if (task.status === "in_progress") {
+        console.log(`that was the last open ask — \`task move ${ask.taskId} done\` if the work is finished too`);
+    }
+}
+/**
+ * `task inbox` — what do I need to do NOW to unblock work: every open ask on
+ * effectively-in-progress tickets (file status, or a live claim branch —
+ * see inbox.ts), across the repo's boards, oldest owed first. Deliberately
+ * cross-board, like `claim --next`: the queue's attention is per-board, a
+ * person's isn't.
+ */
+function cmdInbox(args) {
+    let entries;
+    try {
+        const scope = findScopeRoot(process.cwd());
+        const boards = selectionBoards(process.cwd(), boardFlag(args)).map((store) => {
+            const rel = relative(scope, store.root).split(sep).join("/");
+            return { id: rel === "" ? "." : rel, store };
+        });
+        entries = buildInbox(boards);
+    }
+    catch (error) {
+        if (error instanceof ClaimError)
+            fail(error.message);
+        throw error;
+    }
+    if (args.flags.json) {
+        console.log(JSON.stringify({ inbox: entries }, null, 2));
+        return;
+    }
+    if (entries.length === 0) {
+        console.log("inbox zero — no open asks on in-progress work");
+        return;
+    }
+    const open = entries.reduce((sum, e) => sum + e.asks.length, 0);
+    console.log(`${open} open ask${open === 1 ? "" : "s"} across ${entries.length} ticket${entries.length === 1 ? "" : "s"}`);
+    const age = (iso) => {
+        const days = Math.floor((Date.now() - Date.parse(iso)) / 86_400_000);
+        return days > 0 ? `${days}d` : "today";
+    };
+    for (const entry of entries) {
+        const via = entry.claim ? `  (claimed: ${entry.claim.branch})` : "";
+        console.log(`\n${entry.task.id}  ${entry.task.title}${via}`);
+        for (const ask of entry.asks) {
+            const who = ask.author ? ` · ${ask.author}` : "";
+            console.log(`  [${ask.ordinal}] ${ask.text.split("\n")[0]}  (${age(ask.createdAt)}${who})`);
+        }
+    }
 }
 function cmdComment(args) {
     const [ref, ...rest] = args.positional;
@@ -512,8 +775,8 @@ function cmdLink(args, action) {
     const store = openStoreFor(ref);
     const relation = blocks ? "blocks" : "blocked_by";
     const target = parseRefOn(store, (blocks ?? blockedBy));
-    const number = store.parseId(ref);
-    const task = action === "link" ? store.link(number, relation, target) : store.unlink(number, relation, target);
+    const key = store.parseId(ref);
+    const task = action === "link" ? store.link(key, relation, target) : store.unlink(key, relation, target);
     if (args.flags.json) {
         console.log(JSON.stringify({ task }, null, 2));
     }
@@ -525,39 +788,80 @@ function cmdLink(args, action) {
         console.log(`${subject} ${verb} blocks ${object}`);
     }
 }
+const CLAIM_USAGE = 'usage: task claim <id> | task claim --next | task claim --release <id> --comment "<why>"';
 /**
- * `task claim <id>` / `task claim --release <id>` — see claim.ts for the
- * mechanics. Exit codes are the contract callers script against: 0 claimed,
- * 1 already claimed (pick the next ticket), 2 not claimable (fix something).
+ * `task claim <id>` / `task claim --next` / `task claim --release <id>` — see
+ * claim.ts for the mechanics. Exit codes are the contract callers script
+ * against: 0 claimed, 1 already claimed / queue empty (nothing to do here —
+ * a scheduled worker stops cleanly), 2 preconditions failed (fix something).
  */
 function cmdClaim(args) {
     const ref = args.positional[0];
-    if (!ref)
-        fail("usage: task claim <id> | task claim --release <id>");
-    const store = openStoreFor(ref);
-    const number = store.parseId(ref);
+    const options = { force: Boolean(args.flags.force) };
+    const printClaim = (result) => {
+        if (args.flags.json) {
+            console.log(JSON.stringify({ task: result.task, branch: result.branch }, null, 2));
+        }
+        else {
+            console.log(`claimed ${result.task.id} — on ${result.branch} (from ${result.base}), status in_progress`);
+        }
+    };
     try {
+        if (args.flags.next) {
+            // The first line of every scheduled worker: claim the top claimable
+            // ticket across the selection scope (--board > root `boards` > nearest),
+            // retrying past lost races internally.
+            if (ref)
+                fail("pass an id or --next, not both");
+            if (args.flags.release)
+                fail(CLAIM_USAGE);
+            const result = claimNext(selectionBoards(process.cwd(), boardFlag(args)), options);
+            if (!result) {
+                if (args.flags.json) {
+                    console.log(JSON.stringify({ task: null }, null, 2));
+                }
+                else {
+                    console.log("nothing claimable — no unblocked, unclaimed todo tickets in scope");
+                }
+                process.exit(1);
+            }
+            printClaim(result);
+            return;
+        }
+        if (!ref)
+            fail(CLAIM_USAGE);
+        const store = openStoreFor(ref);
+        const key = store.parseId(ref);
         if (args.flags.release) {
-            const result = release(store, number);
+            // A released claim must leave its failure context behind: the branch
+            // (and whatever was tried on it) is about to evaporate, so the reason
+            // is required, and lands as an ordinary attributed comment.
+            const why = str(args.flags, "comment")?.trim();
+            if (!why) {
+                fail('task claim --release requires --comment "<why>" — the next worker inherits what was tried');
+            }
+            const result = release(store, key);
+            const commented = result.remote || result.local;
+            // After the branch deletion, so the comment survives it: release leaves
+            // the checkout on the default branch, and the comment file sits there
+            // uncommitted, to ride along with the next commit.
+            const comment = commented
+                ? store.addComment(key, why, resolveAuthor(str(args.flags, "author")).name)
+                : null;
             if (args.flags.json) {
-                console.log(JSON.stringify({ released: result }, null, 2));
+                console.log(JSON.stringify({ released: result, comment }, null, 2));
             }
-            else if (!result.remote && !result.local) {
-                console.log(`${store.displayId(number)} wasn't claimed — no ${result.branch} to delete`);
+            else if (!commented) {
+                console.log(`${store.displayId(key)} wasn't claimed — no ${result.branch} to delete`);
             }
             else {
                 const where = [result.remote && "origin", result.local && "local"].filter(Boolean);
-                console.log(`released ${store.displayId(number)} — deleted ${result.branch} (${where.join(" and ")})`);
+                console.log(`released ${store.displayId(key)} — deleted ${result.branch} (${where.join(" and ")})`);
+                console.log(`left the reason as a comment on ${store.displayId(key)} — uncommitted, commit it with your next change`);
             }
             return;
         }
-        const result = claim(store, number);
-        if (args.flags.json) {
-            console.log(JSON.stringify({ task: result.task, branch: result.branch }, null, 2));
-        }
-        else {
-            console.log(`claimed ${result.task.id} — on ${result.branch} (from ${result.base}), status in_progress`);
-        }
+        printClaim(claim(store, key, options));
     }
     catch (error) {
         if (error instanceof ClaimError) {
@@ -567,6 +871,167 @@ function cmdClaim(args) {
         throw error;
     }
 }
+/** `task instructions` — the shipped agent conventions, self-served at runtime. */
+function cmdInstructions() {
+    // skill/ ships in the npm package; `../` from both dist/cli.js and
+    // src/cli.ts is the package root, same trick VERSION uses.
+    process.stdout.write(readFileSync(new URL("../skill/SKILL.md", import.meta.url), "utf8"));
+}
+/** `task overview [--json]` — one screen of board health. See overview.ts. */
+function cmdOverview(args) {
+    const overview = buildOverview(openStore());
+    if (args.flags.json) {
+        console.log(JSON.stringify({ overview }, null, 2));
+        return;
+    }
+    console.log(`${overview.board} (${overview.prefix}) — ${overview.open} open`);
+    console.log(`  ${STATUSES.map((s) => `${STATUS_GLYPH[s]} ${s} ${overview.statuses[s]}`).join("  ")}`);
+    const claimed = overview.claimed === null
+        ? "claimed ? (origin unreachable)"
+        : `claimed ${overview.claimed.length}${overview.claimed.length ? ` (${overview.claimed.join(", ")})` : ""}`;
+    const asks = overview.oldestAsk
+        ? `asks ${overview.openAsks} open (oldest ${overview.oldestAsk.taskId}, ${overview.oldestAsk.createdAt.slice(0, 10)})`
+        : "asks 0 open";
+    console.log(`  ${claimed}   ${asks}`);
+    if (overview.goals.length) {
+        console.log("goals");
+        table(overview.goals.map((g) => [
+            `  ${g.slug}`,
+            g.title,
+            `${g.done}/${g.total} done${g.total ? ` (${Math.round((g.done / g.total) * 100)}%)` : ""}`,
+        ]));
+    }
+    if (overview.stale.length) {
+        console.log(`stale (untouched ${STALE_DAYS}+ days)`);
+        table(overview.stale.map((t) => [`  ${t.id}`, t.title, t.updatedAt.slice(0, 10)]));
+    }
+    if (overview.oldestOpen) {
+        console.log(`oldest open  ${overview.oldestOpen.id}  ${overview.oldestOpen.title}  (created ${overview.oldestOpen.createdAt.slice(0, 10)})`);
+    }
+}
+/**
+ * `task goal …` — the goals a board's tasks belong to. A goal is a titled,
+ * described destination (`.task/goals/<slug>.md`); a task carries at most one.
+ * There is no goal status anywhere here on purpose: progress is derived from
+ * the tasks, and `archive` is the only lifecycle a goal has.
+ */
+function cmdGoal(args) {
+    const [sub, ...rest] = args.positional;
+    const usage = "usage: task goal add <title> [--slug <s>] [--description …] | list [--archived] | " +
+        "show <slug> | update <slug> [--title …] [--description …] | archive <slug> | " +
+        "unarchive <slug> | delete <slug>";
+    if (!sub)
+        fail(usage);
+    const store = openStore();
+    const slugArg = () => {
+        const slug = rest[0];
+        if (!slug)
+            fail(`usage: task goal ${sub} <slug>`);
+        return slug;
+    };
+    const printGoal = (goal, verb) => console.log(`${verb} ${goal.slug}  ${goal.title}${goal.archived ? " (archived)" : ""}`);
+    switch (sub) {
+        case "add": {
+            const title = rest.join(" ").trim();
+            if (!title)
+                fail("usage: task goal add <title> [--slug <s>] [--description …]");
+            const goal = store.createGoal({
+                title,
+                slug: str(args.flags, "slug"),
+                description: str(args.flags, "description") ?? str(args.flags, "desc"),
+            });
+            if (args.flags.json)
+                console.log(JSON.stringify({ goal }, null, 2));
+            else
+                printGoal(goal, "created");
+            return;
+        }
+        case "list": {
+            const archived = Boolean(args.flags.archived);
+            const goals = store.goals(archived);
+            // Progress is derived here, at read time — a goal file never stores it.
+            const tasks = store.list({ statuses: undefined });
+            const rows = goals.map((goal) => {
+                const mine = tasks.filter((t) => t.goal === goal.slug);
+                const done = mine.filter((t) => t.status === "done" || t.status === "canceled").length;
+                return { ...goal, open: mine.length - done, done, total: mine.length };
+            });
+            if (args.flags.json) {
+                console.log(JSON.stringify({ goals: rows }, null, 2));
+            }
+            else if (rows.length === 0) {
+                console.log(archived ? "no archived goals" : "no goals — create one with `task goal add`");
+            }
+            else {
+                table(rows.map((g) => [g.slug, g.title, `${g.done}/${g.total} done`]));
+            }
+            return;
+        }
+        case "show": {
+            const slug = slugArg();
+            const goal = store.getGoal(slug);
+            if (!goal)
+                fail(`no such goal: "${slug}"`);
+            const tasks = store.list({ statuses: undefined, goal: slug });
+            if (args.flags.json) {
+                console.log(JSON.stringify({ goal, tasks }, null, 2));
+                return;
+            }
+            console.log(`${goal.slug}  ${goal.title}`);
+            if (goal.archived)
+                console.log(`archived  yes — \`task goal unarchive ${goal.slug}\` to edit`);
+            console.log(`created   ${goal.createdAt}`);
+            console.log(`updated   ${goal.updatedAt}`);
+            if (goal.description)
+                console.log(`\n${goal.description}`);
+            if (tasks.length) {
+                console.log("");
+                table(tasks.map(taskRow));
+            }
+            return;
+        }
+        case "update": {
+            const patch = {
+                ...(str(args.flags, "title") !== undefined && { title: str(args.flags, "title") }),
+                ...((str(args.flags, "description") ?? str(args.flags, "desc")) !== undefined && {
+                    description: str(args.flags, "description") ?? str(args.flags, "desc"),
+                }),
+            };
+            if (Object.keys(patch).length === 0)
+                fail("nothing to update — pass --title or --description");
+            const goal = store.updateGoal(slugArg(), patch);
+            if (args.flags.json)
+                console.log(JSON.stringify({ goal }, null, 2));
+            else
+                printGoal(goal, "updated");
+            return;
+        }
+        case "archive": {
+            const goal = store.archiveGoal(slugArg());
+            if (args.flags.json)
+                console.log(JSON.stringify({ goal }, null, 2));
+            else
+                printGoal(goal, "archived");
+            return;
+        }
+        case "unarchive": {
+            const goal = store.unarchiveGoal(slugArg());
+            if (args.flags.json)
+                console.log(JSON.stringify({ goal }, null, 2));
+            else
+                printGoal(goal, "unarchived");
+            return;
+        }
+        case "delete": {
+            const slug = slugArg();
+            store.deleteGoal(slug);
+            console.log(`deleted goal ${slug}`);
+            return;
+        }
+        default:
+            fail(usage);
+    }
+}
 const AUTHOR_SOURCE = {
     flag: "--author",
     env: "$TASK_AUTHOR",
@@ -584,35 +1049,52 @@ function cmdWhoami(args) {
     }
 }
 /**
- * `task migrate` — from the legacy committed SQLite database to text-canonical
- * storage: one markdown file per ticket and per comment under .task/tickets/,
- * with the database left on disk as an ignored backup. Additive and safe to
- * re-run planning-wise: it refuses to run twice.
+ * `task check [--fix]` — lint the board files. Git merges and hand-edits are
+ * write paths no CLI code sees, so validation is a command you can run (and
+ * put in pre-commit or CI, where merge-introduced drift gets caught). Covers
+ * every board at or below here, the same set `task serve` would serve. Exits
+ * non-zero while problems remain; `--fix` first applies the mechanical
+ * repairs — pruning dangling references, rewriting files into canonical form.
  */
-function cmdMigrate(args) {
-    const root = findRoot(process.cwd());
-    if (!root)
-        fail("no .task directory found in this directory or any parent — run `task init` first");
-    const result = migrateBoard(root);
+function cmdCheck(args) {
+    const root = checkRoot(process.cwd());
+    const fix = Boolean(args.flags.fix);
+    const result = checkBoards(root, fix);
+    if (result.boards === 0) {
+        fail("no .task directory found in this directory, any parent, or below — run `task init` first");
+    }
+    // In fix mode the fixable issues were just repaired; what's left needs a human.
+    const remaining = fix ? result.issues.filter((issue) => !issue.fixable) : result.issues;
     if (args.flags.json) {
-        console.log(JSON.stringify({ migrated: result }, null, 2));
-        return;
+        console.log(JSON.stringify({ ...result, remaining }, null, 2));
+    }
+    else {
+        for (const file of result.fixed)
+            console.log(`fixed    ${file}`);
+        for (const issue of remaining) {
+            console.log(`${issue.fixable ? "fixable" : "problem"}  ${issue.file}`);
+            console.log(`         ${issue.message}`);
+        }
+        const scope = `${result.files} file${result.files === 1 ? "" : "s"} across ${result.boards} board${result.boards === 1 ? "" : "s"}`;
+        if (remaining.length === 0) {
+            console.log(result.fixed.length ? `fixed ${result.fixed.length}, ${scope} clean` : `ok — ${scope}`);
+        }
+        else {
+            const fixable = remaining.filter((issue) => issue.fixable).length;
+            console.log(`${remaining.length} problem${remaining.length === 1 ? "" : "s"} in ${scope}${fixable ? ` (${fixable} fixable — run \`task check --fix\`)` : ""}`);
+        }
     }
-    console.log(`Migrated ${result.tasks} task${result.tasks === 1 ? "" : "s"} and ${result.comments} comment${result.comments === 1 ? "" : "s"} to .task/tickets/`);
-    console.log(`tasks.db stays on disk as a backup, but it's ignored now — the files are the state.`);
-    console.log(``);
-    console.log(`Next:`);
-    console.log(`  git rm --cached ${join(TASK_DIR, "tasks.db")}     stop tracking the database`);
-    console.log(`  git add ${TASK_DIR}                       commit the tickets`);
+    if (remaining.length > 0)
+        process.exitCode = 1;
 }
 function cmdDelete(args) {
     const ref = args.positional[0];
     if (!ref)
         fail("usage: task delete <id>");
     const store = openStoreFor(ref);
-    const number = store.parseId(ref);
-    store.delete(number);
-    console.log(`deleted ${store.displayId(number)}`);
+    const key = store.parseId(ref);
+    store.delete(key);
+    console.log(`deleted ${store.displayId(key)}`);
 }
 /**
  * Bind the first free port at or after `first`, the way dev servers do: a board
@@ -790,51 +1272,142 @@ subdirectory (it walks up to find .task/, like git).
 
 Usage
   task init [--name <name>] [--prefix <PREFIX>]
-  task add <title> [--description <text>] [--status <s>] [--tags <a,b>]
-                   [--milestone <m>] [--needs-human]
-  task list [--status <s1,s2>] [--tag <a,b>] [--milestone <m>]
+  task add <title> [--description <text> | --description-file <path|->]
+                   [--status <s>] [--tags <a,b>] [--goal <slug>]
+                   [--ask "<text>"]…
+                                new tickets land in backlog (the dump list)
+                                unless --status says otherwise;
+                                --description-file reads markdown from a file
+                                (or stdin with -) — no shell-quoting fights;
+                                --ask (repeatable) files what a person owes
+                                the ticket, right at creation
+  task list [--status <s1,s2>] [--tag <a,b>] [--goal <slug>]
             [--needs-human] [--all] [--archived] [--claimable]
-  task show <id>
-  task update <id> [--title <t>] [--description <text>] [--status <s>]
-                   [--tags <a,b>] [--milestone <m>]
-                   [--needs-human | --no-needs-human]
+  task search <query> [--status <s1,s2>] [--tag <a,b>] [--goal <slug>]
+                      [--needs-human] [--archived]
+                                find tickets by what they say — case-insensitive
+                                match over titles, descriptions and comments,
+                                with a snippet of the matching line. --archived
+                                searches the archive too, on top of the board
+  task show <id>                the ticket, its comments — and its goal's title
+                                and description inline, so a cold pickup gets
+                                the shared context without chasing it
+  task update <id> [--title <t>] [--description <text> | --description-file <path|->]
+                   [--status <s>] [--tags <a,b>] [--goal <slug>]
                    [--pr <url>] [--prs <url1,url2>]
-  task move <id> <status>       shorthand for update --status
-  task start <id>               → in_progress
-  task done <id>                → done
+  task move <id> <status>       change a ticket's status — the one general
+                                status API (backlog todo in_progress done
+                                canceled). Moving to done is refused while
+                                the ticket has open asks: done means nobody
+                                owes anything. The named verbs below exist
+                                only where a transition does more than write
+                                the status field
+  task ask <id> "<text>"        file an ask: one thing a person owes this
+                                ticket before it can be done. Asks derive the
+                                needs-human badge, feed \`task inbox\`, and
+                                gate \`done\` — they never block claiming (an
+                                agent works the code while a person mints the
+                                token; a true precondition is a blocked_by on
+                                a thin human ticket instead)
+  task resolve <id> <n> [--comment "<note>"] [--reopen]
+                                check ask <n> off (\`task show\` prints the
+                                ordinals); the note lands as an attributed
+                                comment. --reopen puts a resolved ask back
+  task inbox [--board <P>]      what needs YOU, now: every open ask on
+                                effectively in-progress tickets — file status
+                                in_progress, or a live claim branch on origin
+                                (a claimed ticket is in progress whatever the
+                                merged file says, and its asks are read from
+                                the branch). Cross-board like claim --next;
+                                oldest owed first. Backlog/todo asks are out
+                                by design — claiming is what makes them yours
+  task promote <id>             backlog → todo, the human "build this" call.
+                                No quality gate — planning happens at claim
+                                time. Blocked tickets still promote —
+                                blockers are claim-time gates, reported as a
+                                note — so promoting can queue work behind
+                                its blockers. Exit codes: 0 promoted, 2
+                                refused (not a backlog ticket)
   task link <id> --blocked-by <id>
   task link <id> --blocks <id>  mark a dependency — one relation, visible from
                                 both tasks (A blocked by B ⇔ B blocks A)
   task unlink <id> (--blocks <id> | --blocked-by <id>)
-  task claim <id>               claim a ticket before working it: branch
-                                <claimPrefix><prefix>-<n> off origin's default
-                                branch, ticket → in_progress as its first
-                                commit, pushed. The namespace defaults to
-                                task/claim/ — set "claimPrefix" in
+  task claim <id> [--force]     claim a ticket before working it: branch
+                                <branchPrefix><prefix>-<key> off origin's
+                                default branch, ticket → in_progress as its
+                                first commit, pushed. The namespace defaults
+                                to task/claim/ — set claims.branchPrefix in
                                 .task/config.json to change it (e.g.
                                 "claude/task/", which Claude cloud sessions
                                 can push). Branch on origin = claimed —
                                 git's atomic ref creation is the lock, so two
-                                concurrent claimers can't both win. Exit codes:
+                                concurrent claimers can't both win. While the
+                                root board sets claims.maxOpenCount and that
+                                many claim branches exist on origin, claiming
+                                is refused (--force overrides). Exit codes:
                                 0 claimed, 1 already claimed, 2 not claimable
-                                (not todo, blocked, needs-human, dirty tree)
-  task claim --release <id>     abandon a claim: delete the branch on origin
+                                (not todo, blocked, dirty tree, at the cap)
+  task claim --next [--board <P>] [--force]
+                                claim the top claimable ticket in one call,
+                                retrying past lost races internally — the
+                                first line of every scheduled worker. Scope:
+                                --board prefixes (repeatable, given order =
+                                priority) > the root board's "boards" list >
+                                the nearest board. Exit codes: 0 claimed
+                                (prints the ticket), 1 queue empty, 2
+                                preconditions failed
+  task claim --release <id> --comment "<why>"
+                                abandon a claim: delete the branch on origin
                                 and locally — the status flip only lived on
-                                the branch, so deleting it is the revert
-  task list --claimable         the claim queue: todo tickets in position
-                                order, minus blocked / needs-human / already
-                                claimed on origin. Top entry is next up
+                                the branch, so deleting it is the revert. The
+                                comment is required and lands on the ticket
+                                (attributed like task comment, uncommitted),
+                                so the next worker inherits what was tried
+  task list --claimable [--board <P>]
+                                the claim queue: todo tickets in position
+                                order, minus blocked / already claimed on
+                                origin. Top entry is next up. Same board
+                                scope as claim --next
+  task instructions             print the shipped agent conventions
+                                (skill/SKILL.md) — agents without the skill
+                                installed self-serve the house rules
+  task overview [--json]        one screen of board health: counts per
+                                status, per-goal progress, claimed and
+                                open-ask counts, stale tickets (untouched
+                                ${STALE_DAYS}+ days), oldest open ticket
   task comment <id> <text> [--author <who>]
   task delete <id>
+  task goal add <title> [--slug <s>] [--description <text>]
+                                create a goal: a titled, described destination
+                                tasks belong to (.task/goals/<slug>.md). The
+                                description is the strategic why — the context
+                                every ticket under it shares
+  task goal list [--archived]   every goal with derived progress (done/total —
+                                a goal stores no status of its own, ever)
+  task goal show <slug>         the goal, its description, and its tasks
+  task goal update <slug> [--title <t>] [--description <text>]
+  task goal archive <slug>      shelve a finished/abandoned goal — refused
+                                while it still has open tasks
+  task goal unarchive <slug>
+  task goal delete <slug>       only when no live task references it
   task boards                   every board in this repo — prefix, name, path,
                                 open count; * marks the one commands target here
   task archive <id>             move a done/canceled ticket to .task/archive/,
                                 out of the board and off the hot path — still
                                 readable via show and list --archived, and its
-                                number stays reserved
+                                key stays reserved
   task archive --all            archive everything done or canceled
   task unarchive <id>           put an archived ticket back on the board
   task whoami                   who your comments are attributed to
+  task check [--fix]            lint the board files — merges and hand-edits
+                                are write paths no CLI code sees. Reports
+                                unparseable files, dangling blocked_by refs,
+                                bad timestamps, unknown frontmatter keys and
+                                formatting drift, for every board at or below
+                                here; exits non-zero while problems remain.
+                                --fix applies the mechanical repairs first
+                                (prune dangling refs, rewrite to canonical
+                                form). Cheap enough for pre-commit and CI
   task serve [--port <n>] [--no-open] [--strict-port]
                                 board + table UI with live updates, opened in
                                 your browser (default port ${DEFAULT_PORT}; taken ports
@@ -852,19 +1425,22 @@ Usage
   task unpublish [--repo <owner/name>]
                                 take that URL down. Removes the board, not the
                                 tasks — those are in .task/ either way
-  task migrate                  move a pre-0.6 board off its committed SQLite
-                                database and onto text files in .task/tickets/.
-                                The database stays on disk as an ignored backup
 
 Values
-  <id>          TAS-12, or just 12. A bare number means the nearest board; a
-                prefixed id routes to whichever board in the repo owns that
-                prefix, so TAS-12 works from anywhere in a monorepo
+  <id>          TAS-x7k4m, x7k4m, or any unique prefix of a key (task show x7
+                works, git-style — ambiguity is an error naming the matches).
+                Ids are random 5-character keys, minted branch-safely at
+                \`task add\`. A bare key means the nearest board; a prefixed id
+                routes to whichever board in the repo owns that prefix, so
+                TAS-x7k4m works from anywhere in a monorepo
   status        ${STATUSES.join("  ")}
   --tag a,b     matches a task carrying *either* tag
-  --needs-human this can't be finished by an agent alone
+  --goal <slug> a task belongs to at most one goal. Goals answer "where is
+                this going" (one); tags answer "what kind" (many) — something
+                that wants two goals is a tag
+  --needs-human filter: tickets with open asks — something a person owes
   --pr <url>    attach a pull request (appends); --prs replaces the whole list
-  clearing      --tags "" drops all tags, --milestone "" clears it, --prs ""
+  clearing      --tags "" drops all tags, --goal "" clears it, --prs ""
                 detaches all PRs
 
 Comment authors resolve --author → $TASK_AUTHOR → git config user.name →
@@ -892,22 +1468,34 @@ function main() {
             return cmdAdd(args);
         case "list":
             return cmdList(args);
+        case "search":
+            return cmdSearch(args);
         case "show":
             return cmdShow(args);
         case "update":
             return cmdUpdate(args);
         case "move":
             return cmdMove(args);
-        case "start":
-            return cmdUpdate(args, "in_progress");
-        case "done":
-            return cmdUpdate(args, "done");
+        case "promote":
+            return cmdPromote(args);
         case "link":
             return cmdLink(args, "link");
         case "unlink":
             return cmdLink(args, "unlink");
         case "claim":
             return cmdClaim(args);
+        case "instructions":
+            return cmdInstructions();
+        case "ask":
+            return cmdAsk(args);
+        case "resolve":
+            return cmdResolve(args);
+        case "inbox":
+            return cmdInbox(args);
+        case "overview":
+            return cmdOverview(args);
+        case "goal":
+            return cmdGoal(args);
         case "comment":
             return cmdComment(args);
         case "whoami":
@@ -920,8 +1508,8 @@ function main() {
             return cmdArchive(args);
         case "unarchive":
             return cmdUnarchive(args);
-        case "migrate":
-            return cmdMigrate(args);
+        case "check":
+            return cmdCheck(args);
         case "serve":
             return cmdServe(args);
         case "publish":