@nickmeriano/task 0.4.2 → 0.6.0

package/README.md

@@ -3,10 +3,12 @@
 A task manager that lives in your repo.
 
 Tasks and their status are coupled to the code — so keep them next to it.
-State is a SQLite database in `.task/` at your project root: no accounts, no
-connectors, no drift between the board and the branch. Built for the way
-projects work now — you *and* your AI agents share one backlog, and the board
-updates live while agents move tickets from another terminal.
+State is plain text in `.task/` at your project root — one markdown file per
+ticket and per comment: no accounts, no connectors, no drift between the board
+and the branch. Ticket changes show up as readable diffs in PRs, and two
+branches editing different tickets merge cleanly. Built for the way projects
+work now — you *and* your AI agents share one backlog, and the board updates
+live while agents move tickets from another terminal.
 
 ```bash
 npx @nickmeriano/task init
@@ -43,7 +45,11 @@ task list                      # open tasks, board order
 task list --needs-human        # what's blocked on a person
 task start 1                   # → in_progress
 task done 1                    # → done
+task link 2 --blocked-by 1     # dependency, visible from both tasks
+task update 1 --pr https://github.com/you/repo/pull/42
 task comment 1 "shipped in #42" --author claude
+task boards                    # every board in the repo, with prefixes
+task archive --all             # move finished tickets to .task/archive/
 task serve                     # opens the kanban + table UI, live
 task publish                   # same board, at a URL you can open on a phone
 ```
@@ -81,11 +87,68 @@ one committing.
   immediately; your tasks are untouched, because they were only ever read from
   `.task/`. Changing your mind about *visibility* doesn't need that at all —
   `task publish --private` is enough.
+- **Any branch.** The board renders your default branch, but `?ref=<branch>`
+  renders any other — and the header grows a branch switcher when there's more
+  than one. That's PR review for board changes: see the board as the PR would
+  leave it, before merging. Locally none of this is needed — `task serve`
+  shows your working tree, so previewing a branch is `git checkout`.
+
+Since the preview URL is predictable, a small workflow in *your* repo can
+comment it on every PR that touches board state — the App itself stays
+read-only and never writes to your repository:
+
+```yaml
+# .github/workflows/board-preview.yml
+name: Board preview
+on:
+  pull_request:
+    paths: [".task/**", "**/.task/**"]
+permissions:
+  pull-requests: write
+jobs:
+  comment:
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const branch = context.payload.pull_request.head.ref
+            const url = `https://task.nickmeriano.com/${context.repo.owner}/${context.repo.repo}?ref=${encodeURIComponent(branch)}`
+            const marker = "<!-- board-preview -->"
+            const body = `${marker}\n📋 [Preview the board at \`${branch}\`](${url})`
+            const comments = await github.paginate(github.rest.issues.listComments, { ...context.repo, issue_number: context.issue.number })
+            const existing = comments.find((c) => c.body?.startsWith(marker))
+            if (existing) await github.rest.issues.updateComment({ ...context.repo, comment_id: existing.id, body })
+            else await github.rest.issues.createComment({ ...context.repo, issue_number: context.issue.number, body })
+```
 
-- Ids are `PREFIX-12` or just `12`; the prefix comes from `task init --prefix`.
+- Ids are `PREFIX-12` or just `12`; the prefix is the first three letters of
+  the project name ("phone" → `PHO-1`), or whatever `task init --prefix` says.
+- Ids route by prefix: a bare `12` means the nearest board, while `TAS-12`
+  reaches the TAS board from anywhere in the monorepo. An unknown or ambiguous
+  prefix fails loudly instead of guessing. `task boards` lists every board —
+  prefix, name, path, open count — with a `*` on the one commands target from
+  the current directory.
+- `task archive <id>` moves a done/canceled ticket's directory to
+  `.task/archive/` — off the board and out of every hot path, so boards stay
+  fast as history accumulates. Archived tickets stay readable (`task show`,
+  `task list --archived`), keep their comments, and their numbers stay
+  reserved forever. `task archive --all` sweeps everything finished;
+  `task unarchive <id>` puts one back.
 - Statuses: `backlog` `todo` `in_progress` `done` `canceled`.
 - A task carries tags, at most one milestone, and a `--needs-human` flag for
   work an agent can't finish alone. `--tag a,b` matches either tag.
+- `task link A --blocked-by B` marks a dependency. It's one relation seen from
+  both ends — B's page says it blocks A — and the board badges A as blocked
+  until B is done or canceled.
+- `--pr <url>` attaches a pull request to a task (`--prs` replaces the list);
+  attached PRs show in the task's rail and as a count on its card. The elegant
+  loop is an agent convention, not a webhook: put the id in the PR title
+  (`[TAS-6] …`) and run `task update TAS-6 --pr <url>` when opening the PR —
+  the shipped skill tells agents to do exactly that.
+- Every task has **Copy link** — the icon next to its title, or right-click /
+  long-press any card or row — so handing a ticket to an agent is one paste.
 - Comments are attributed from `git config user.name` with no setup —
   override with `--author` or `$TASK_AUTHOR`, and check with `task whoami`.
 - Every command takes `--json` — that's the agent interface.
@@ -100,13 +163,18 @@ one committing.
   root and it serves every nested board from one server, with a board switcher
   in the header. Run it inside a package and you get just that board. Every
   other command stays scoped to the nearest `.task/`.
-- The database self-migrates when it's opened, so pulling a colleague's
-  `.task/` and running any command brings it up to date in place.
+- Boards from before 0.6 stored their state as a committed SQLite database;
+  those keep working as-is, and `task migrate` moves one onto text files
+  (the database stays on disk as an ignored backup).
 
 ## How it's built
 
-- **Zero dependencies.** Storage is Node's built-in `node:sqlite` (Node ≥
-  22.13) — nothing to compile, so `npx` starts in about a second.
+- **Zero dependencies.** Storage is markdown files with a tiny frontmatter
+  block — reviewable in a PR, mergeable by git, editable by hand. Comments are
+  one file each (append-only merges cleanly), and the `blocks`/`blocked-by`
+  relation is stored on one side only, so its two views can't disagree.
+  Legacy boards read through Node's built-in `node:sqlite` (Node ≥ 22.13) —
+  nothing to compile, so `npx` starts in about a second.
 - **Realtime is a file watch.** `task serve` is one `node:http` process: the
   prebuilt UI, a JSON API, and a server-sent-events stream that pings whenever
   anything writes to `.task/` — this UI, another terminal, an agent mid-run.

package/dist/cli.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 // The `task` CLI — tasks that live in your repo. Zero dependencies: hand-rolled
-// flag parsing, node:sqlite for storage, plain text out (--json for agents).
+// 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).
 //
 //   task init
 //   task add "Wire up webhooks" --tags api,infra --milestone launch
 //   task list --status todo,in_progress
-//   task start TASK-3 && task done TASK-3
+//   task start TAS-3 && task done TAS-3
 //   task serve
 import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
@@ -14,7 +16,8 @@ import process from "node:process";
 import { resolveAuthor } from "./author.js";
 import { detectRepo, parseSlug, publish, resolveHost } from "./publish.js";
 import { createTaskServer } from "./server.js";
-import { CONFIG_FILE, TASK_DIR, TaskStore, findBoards, findRoot, initProject } from "./store.js";
+import { initProject, migrateBoard, 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.
@@ -47,6 +50,7 @@ const BOOLEAN_FLAGS = new Set([
     "yes",
     "needs-human",
     "no-needs-human",
+    "archived",
     "open",
     "no-open",
     "strict-port",
@@ -90,7 +94,62 @@ function openStore() {
     const root = findRoot(process.cwd());
     if (!root)
         fail("no .task directory found in this directory or any parent — run `task init` first");
-    return new TaskStore(root);
+    return openBoard(root);
+}
+/** The prefix a ref carries, if any: "TAS-12" → "TAS", "12" → null. */
+function refPrefix(ref) {
+    const match = /^([A-Za-z0-9]+)-\d+$/.exec(ref.trim());
+    return match ? match[1].toUpperCase() : null;
+}
+/**
+ * The board a ref belongs to. A bare number 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
+ * 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.
+ */
+function openStoreFor(ref) {
+    const prefix = ref ? refPrefix(ref) : null;
+    if (!prefix)
+        return openStore();
+    const nearest = findRoot(process.cwd());
+    if (nearest) {
+        const store = openBoard(nearest);
+        if (store.config.prefix.toUpperCase() === prefix)
+            return store;
+        store.close();
+    }
+    const scope = findScopeRoot(process.cwd());
+    const matches = findBoardsByPrefix(scope, prefix);
+    if (matches.length === 1)
+        return openBoard(matches[0].root);
+    if (matches.length > 1) {
+        fail(`prefix ${prefix} is ambiguous — boards at: ${matches.map((m) => m.id).join(", ")}`);
+    }
+    const known = findBoards(scope)
+        .map((b) => {
+        try {
+            return `${boardConfig(b.root).prefix} (${b.id})`;
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter(Boolean);
+    fail(`no board with prefix ${prefix} in this repo${known.length ? ` — boards here: ${known.join(", ")}` : ""}`);
+}
+/**
+ * Parse a ref against an already-chosen board, refusing a foreign prefix
+ * instead of reinterpreting it — this guards the second id in `task link`,
+ * where the board was picked by the first.
+ */
+function parseRefOn(store, ref) {
+    const prefix = refPrefix(ref);
+    if (prefix && prefix !== store.config.prefix.toUpperCase()) {
+        fail(`${ref} is not on the ${store.config.prefix} board — links can't cross boards`);
+    }
+    return store.parseId(ref);
 }
 // ── Input normalization ──────────────────────────────────────────────────────
 function parseStatus(value) {
@@ -123,6 +182,11 @@ function patchFromFlags(flags) {
         patch.needsHuman = true;
     if (flags["no-needs-human"])
         patch.needsHuman = false;
+    // Replace semantics like --tags; `--pr` (append one) is handled per-command
+    // because appending needs the task's current list.
+    const prs = str(flags, "prs");
+    if (prs !== undefined)
+        patch.prs = prs.split(",").map((p) => p.trim()).filter(Boolean);
     return patch;
 }
 // ── Output helpers ───────────────────────────────────────────────────────────
@@ -179,7 +243,11 @@ function cmdAdd(args) {
     if (!title)
         fail(`usage: task add <title> [--description …] [--status …] [--tags a,b] [--milestone …] [--needs-human]`);
     const store = openStore();
-    const task = store.create({ title, ...patchFromFlags(args.flags) });
+    const patch = patchFromFlags(args.flags);
+    const pr = str(args.flags, "pr");
+    if (pr)
+        patch.prs = [...(patch.prs ?? []), pr];
+    const task = store.create({ title, ...patch });
     if (args.flags.json) {
         console.log(JSON.stringify({ task }, null, 2));
     }
@@ -189,18 +257,22 @@ function cmdAdd(args) {
 }
 function cmdList(args) {
     const store = openStore();
+    const archived = Boolean(args.flags.archived);
     const statusFlag = str(args.flags, "status");
     const statuses = statusFlag
         ? statusFlag.split(",").map(parseStatus)
-        : args.flags.all
-            ? undefined
-            : ["backlog", "todo", "in_progress"];
+        : // The archive is all done/canceled, and --all already means everything —
+            // the open-tickets default only applies to the plain board listing.
+            args.flags.all || archived
+                ? undefined
+                : ["backlog", "todo", "in_progress"];
     const tagFlag = str(args.flags, "tags") ?? str(args.flags, "tag");
     const tasks = store.list({
         statuses,
         tags: tagFlag ? parseTags(tagFlag) : undefined,
         milestone: str(args.flags, "milestone"),
         needsHuman: args.flags["needs-human"] ? true : undefined,
+        archived: archived || undefined,
     });
     // Present in board order: grouped by status column, then position.
     const order = new Map(STATUSES.map((s, i) => [s, i]));
@@ -209,17 +281,110 @@ function cmdList(args) {
         console.log(JSON.stringify({ tasks }, null, 2));
     }
     else if (tasks.length === 0) {
-        console.log(args.flags.all ? "no tasks" : "no open tasks (--all includes done/canceled)");
+        console.log(archived
+            ? "no archived tasks"
+            : args.flags.all
+                ? "no tasks"
+                : "no open tasks (--all includes done/canceled)");
     }
     else {
         table(tasks.map(taskRow));
     }
 }
+/**
+ * `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
+ * in a monorepo. The `*` marks the board the other commands would target from
+ * here.
+ */
+function cmdBoards(args) {
+    const cwd = process.cwd();
+    const scope = findScopeRoot(cwd);
+    const boards = findBoards(scope);
+    if (boards.length === 0) {
+        fail("no .task directory found in this directory, any parent, or below — run `task init` first");
+    }
+    const nearest = findRoot(cwd);
+    const rows = boards.map((ref) => {
+        const store = openBoard(ref.root);
+        const open = store.list({ statuses: ["backlog", "todo", "in_progress"] }).length;
+        store.close();
+        return {
+            id: ref.id,
+            name: store.config.name,
+            prefix: store.config.prefix,
+            open,
+            current: ref.root === nearest,
+        };
+    });
+    if (args.flags.json) {
+        console.log(JSON.stringify({ boards: rows }, null, 2));
+    }
+    else {
+        table(rows.map((b) => [
+            b.current ? "*" : "",
+            b.prefix,
+            b.name,
+            b.id,
+            `${b.open} open`,
+        ]));
+    }
+}
+/**
+ * `task archive <id>` / `task archive --all` — move finished tickets to
+ * `.task/archive/`, out of the board and off every hot path. History, not a
+ * hiding place: only done/canceled tickets qualify, everything stays readable
+ * via `show` and `list --archived`, and `task unarchive` puts one back.
+ */
+function cmdArchive(args) {
+    const ref = args.positional[0];
+    if (args.flags.all && ref)
+        fail("pass an id or --all, not both");
+    if (!args.flags.all && !ref)
+        fail("usage: task archive <id> | task archive --all");
+    if (ref) {
+        const store = openStoreFor(ref);
+        const task = store.archive(store.parseId(ref));
+        if (args.flags.json) {
+            console.log(JSON.stringify({ task }, null, 2));
+        }
+        else {
+            console.log(`archived ${task.id}  ${task.title}`);
+        }
+        return;
+    }
+    const store = openStore();
+    const finished = store.list({ statuses: ["done", "canceled"] });
+    const archived = finished.map((t) => store.archive(t.number));
+    if (args.flags.json) {
+        console.log(JSON.stringify({ archived }, null, 2));
+    }
+    else if (archived.length === 0) {
+        console.log("nothing to archive — no done or canceled tasks on the board");
+    }
+    else {
+        for (const task of archived)
+            console.log(`archived ${task.id}  ${task.title}`);
+    }
+}
+function cmdUnarchive(args) {
+    const ref = args.positional[0];
+    if (!ref)
+        fail("usage: task unarchive <id>");
+    const store = openStoreFor(ref);
+    const task = store.unarchive(store.parseId(ref));
+    if (args.flags.json) {
+        console.log(JSON.stringify({ task }, null, 2));
+    }
+    else {
+        printTask(task);
+    }
+}
 function cmdShow(args) {
     const ref = args.positional[0];
     if (!ref)
         fail("usage: task show <id>");
-    const store = openStore();
+    const store = openStoreFor(ref);
     const number = store.parseId(ref);
     const task = store.get(number);
     if (!task)
@@ -229,14 +394,29 @@ function cmdShow(args) {
         console.log(JSON.stringify({ task, comments }, 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);
+    })
+        .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`);
     if (task.tags.length)
         console.log(`tags      ${task.tags.join(", ")}`);
     if (task.milestone)
         console.log(`milestone ${task.milestone}`);
+    if (task.blockedBy.length)
+        console.log(`blocked   by ${describeLinks(task.blockedBy)}`);
+    if (task.blocks.length)
+        console.log(`blocks    ${describeLinks(task.blocks)}`);
+    for (const pr of task.prs)
+        console.log(`pr        ${pr}`);
     console.log(`created   ${task.createdAt}`);
     console.log(`updated   ${task.updatedAt}`);
     if (task.description)
@@ -253,13 +433,20 @@ function cmdUpdate(args, forcedStatus) {
     const ref = args.positional[0];
     if (!ref)
         fail("usage: task update <id> [--status …] [--title …] …");
-    const store = openStore();
+    const store = openStoreFor(ref);
+    const number = 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 ?? [];
+        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(store.parseId(ref), patch);
+    const task = store.update(number, patch);
     if (args.flags.json) {
         console.log(JSON.stringify({ task }, null, 2));
     }
@@ -278,7 +465,7 @@ function cmdComment(args) {
     const body = rest.join(" ").trim();
     if (!ref || !body)
         fail(`usage: task comment <id> <text> [--author <who>]`);
-    const store = openStore();
+    const store = openStoreFor(ref);
     const author = resolveAuthor(str(args.flags, "author")).name;
     const comment = store.addComment(store.parseId(ref), body, author);
     if (args.flags.json) {
@@ -288,6 +475,34 @@ function cmdComment(args) {
         console.log(`commented on ${comment.taskId}`);
     }
 }
+/**
+ * `task link TAS-3 --blocked-by TAS-5` / `task unlink TAS-3 --blocks TAS-9`.
+ * One relation with two spellings: either flag writes the same (blocker,
+ * blocked) row, so the other task's `task show` reflects it immediately.
+ */
+function cmdLink(args, action) {
+    const ref = args.positional[0];
+    const blocks = str(args.flags, "blocks");
+    const blockedBy = str(args.flags, "blocked-by");
+    if (!ref || (blocks ? blockedBy : !blockedBy)) {
+        fail(`usage: task ${action} <id> (--blocks <id> | --blocked-by <id>)`);
+    }
+    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);
+    if (args.flags.json) {
+        console.log(JSON.stringify({ task }, null, 2));
+    }
+    else {
+        const verb = action === "link" ? "now" : "no longer";
+        const [subject, object] = relation === "blocks"
+            ? [task.id, store.displayId(target)]
+            : [store.displayId(target), task.id];
+        console.log(`${subject} ${verb} blocks ${object}`);
+    }
+}
 const AUTHOR_SOURCE = {
     flag: "--author",
     env: "$TASK_AUTHOR",
@@ -304,11 +519,33 @@ function cmdWhoami(args) {
         console.log(`${author.name}  (${AUTHOR_SOURCE[author.source]})`);
     }
 }
+/**
+ * `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.
+ */
+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);
+    if (args.flags.json) {
+        console.log(JSON.stringify({ migrated: result }, null, 2));
+        return;
+    }
+    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`);
+}
 function cmdDelete(args) {
     const ref = args.positional[0];
     if (!ref)
         fail("usage: task delete <id>");
-    const store = openStore();
+    const store = openStoreFor(ref);
     const number = store.parseId(ref);
     store.delete(number);
     console.log(`deleted ${store.displayId(number)}`);
@@ -481,8 +718,10 @@ function runPublishFlow(args, repo, action, visibility) {
 // ── Help + dispatch ──────────────────────────────────────────────────────────
 const HELP = `task — a task manager that lives in your repo
 
-State is a SQLite database in .task/ at the project root. Commit it: tasks and
-their status travel with the code they describe. Any command works from any
+State is plain text in .task/ at the project root — one markdown file per
+ticket and per comment under .task/tickets/. Commit it: tasks travel with the
+code they describe, ticket changes show up as readable diffs in PRs, and two
+branches editing different tickets merge cleanly. Any command works from any
 subdirectory (it walks up to find .task/, like git).
 
 Usage
@@ -490,16 +729,29 @@ Usage
   task add <title> [--description <text>] [--status <s>] [--tags <a,b>]
                    [--milestone <m>] [--needs-human]
   task list [--status <s1,s2>] [--tag <a,b>] [--milestone <m>]
-            [--needs-human] [--all]
+            [--needs-human] [--all] [--archived]
   task show <id>
   task update <id> [--title <t>] [--description <text>] [--status <s>]
                    [--tags <a,b>] [--milestone <m>]
                    [--needs-human | --no-needs-human]
+                   [--pr <url>] [--prs <url1,url2>]
   task move <id> <status>       shorthand for update --status
   task start <id>               → in_progress
   task done <id>                → done
+  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 comment <id> <text> [--author <who>]
   task delete <id>
+  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
+  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 serve [--port <n>] [--no-open] [--strict-port]
                                 board + table UI with live updates, opened in
@@ -518,13 +770,20 @@ 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>          TASK-12, or just 12
+  <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
   status        ${STATUSES.join("  ")}
   --tag a,b     matches a task carrying *either* tag
   --needs-human this can't be finished by an agent alone
-  clearing      --tags "" drops all tags, --milestone "" clears it
+  --pr <url>    attach a pull request (appends); --prs replaces the whole list
+  clearing      --tags "" drops all tags, --milestone "" clears it, --prs ""
+                detaches all PRs
 
 Comment authors resolve --author → $TASK_AUTHOR → git config user.name →
 anonymous, so there is nothing to set up. \`task whoami\` shows which one won.
@@ -561,12 +820,24 @@ function main() {
             return cmdUpdate(args, "in_progress");
         case "done":
             return cmdUpdate(args, "done");
+        case "link":
+            return cmdLink(args, "link");
+        case "unlink":
+            return cmdLink(args, "unlink");
         case "comment":
             return cmdComment(args);
         case "whoami":
             return cmdWhoami(args);
         case "delete":
             return cmdDelete(args);
+        case "boards":
+            return cmdBoards(args);
+        case "archive":
+            return cmdArchive(args);
+        case "unarchive":
+            return cmdUnarchive(args);
+        case "migrate":
+            return cmdMigrate(args);
         case "serve":
             return cmdServe(args);
         case "publish":