@nickmeriano/task 0.7.1 → 0.9.0

package/src/cli.ts

@@ -1,25 +1,37 @@
 #!/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 type { Server } from "node:http"
-import { basename, join } from "node:path"
+import { basename, join, relative, sep } from "node:path"
 import process from "node:process"
 import { resolveAuthor } from "./author.ts"
-import { ClaimError, claim, claimableTasks, release } from "./claim.ts"
+import { checkBoards, checkRoot } from "./check.ts"
+import {
+  ClaimError,
+  claim,
+  claimNext,
+  claimableTasks,
+  promote,
+  release,
+  selectionBoards,
+} from "./claim.ts"
+import { addAskRouted, setAskResolvedRouted } from "./claim-io.ts"
+import { buildInbox, type InboxEntry } from "./inbox.ts"
+import { STALE_DAYS, buildOverview } from "./overview.ts"
+import { searchStore } from "./search.ts"
 import { detectRepo, parseSlug, publish, resolveHost } from "./publish.ts"
 import { createTaskServer } from "./server.ts"
-import { initProject, migrateBoard, openBoard } from "./file-store.ts"
+import { initProject, openBoard } from "./file-store.ts"
 import {
   CONFIG_FILE,
   TASK_DIR,
@@ -32,13 +44,6 @@ import {
 } from "./store.ts"
 import { STATUSES, isStatus, type Status, type Task, type TaskPatch } from "./types.ts"
 
-// 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
@@ -63,6 +68,8 @@ const PORT_ATTEMPTS = 20
 interface Args {
   positional: string[]
   flags: Record<string, string | boolean>
+  /** Values of MULTI_FLAGS, in given order — e.g. multi.ask from `--ask "…"`. */
+  multi: Record<string, string[]>
 }
 
 // Every valueless flag has to be listed here: an unregistered one swallows the
@@ -74,7 +81,6 @@ const BOOLEAN_FLAGS = new Set([
   "version",
   "yes",
   "needs-human",
-  "no-needs-human",
   "archived",
   "claimable",
   "release",
@@ -84,28 +90,56 @@ 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: string[]): Args {
   const positional: string[] = []
   const flags: Record<string, string | boolean> = {}
+  const multi: Record<string, string[]> = {}
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]
     if (arg.startsWith("--")) {
       const name = arg.slice(2)
+      const set = (key: string, value: string): void => {
+        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: Args["flags"], name: string): string | undefined {
@@ -124,19 +158,19 @@ function openStore(): Store {
   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: string): string | null {
-  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: string | undefined): Store {
   const prefix = ref ? refPrefix(ref) : null
@@ -174,7 +208,7 @@ function openStoreFor(ref: string | undefined): Store {
  * instead of reinterpreting it — this guards the second id in `task link`,
  * where the board was picked by the first.
  */
-function parseRefOn(store: Store, ref: string): number {
+function parseRefOn(store: Store, ref: string): string {
   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`)
@@ -199,15 +233,27 @@ function patchFromFlags(flags: Args["flags"]): TaskPatch {
   const title = str(flags, "title")
   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")
@@ -241,7 +287,7 @@ function taskRow(t: Task): string[] {
     t.needsHuman ? "⚑" : "",
     t.title,
     t.tags.join(","),
-    t.milestone ?? "",
+    t.goal ?? "",
   ]
 }
 
@@ -272,28 +318,51 @@ function cmdInit(args: Args): void {
 
 function cmdAdd(args: Args): void {
   const title = args.positional.join(" ").trim()
-  if (!title) fail(`usage: task add <title> [--description …] [--status …] [--tags a,b] [--milestone …] [--needs-human]`)
+  if (!title) 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: Args): string[] | undefined {
+  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: Args): void {
-  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.
     for (const flag of ["status", "all", "archived"]) {
       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: Task[]
+    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))
     } else if (tasks.length === 0) {
@@ -303,6 +372,8 @@ function cmdList(args: Args): void {
     }
     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
@@ -316,7 +387,7 @@ function cmdList(args: Args): void {
   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,
   })
@@ -338,6 +409,53 @@ function cmdList(args: Args): void {
   }
 }
 
+/**
+ * `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: Args): void {
+  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
@@ -403,7 +521,7 @@ function cmdArchive(args: Args): void {
 
   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))
   } else if (archived.length === 0) {
@@ -429,34 +547,54 @@ function cmdShow(args: Args): void {
   const ref = args.positional[0]
   if (!ref) fail("usage: task show <id>")
   const store = openStoreFor(ref)
-  const number = store.parseId(ref)
-  const task = store.get(number)
-  if (!task) fail(`no such task: ${store.displayId(number)}`)
-  const comments = store.comments(number)
+  const key = store.parseId(ref)
+  const task = store.get(key)
+  if (!task) 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: number[]): string =>
-    numbers
-      .map((n) => {
-        const other = store.get(n)
-        return other ? `${other.id} (${other.status})` : store.displayId(n)
+  const describeLinks = (keys: string[]): string =>
+    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) 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) 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) {
@@ -466,21 +604,20 @@ function cmdShow(args: Args): void {
   }
 }
 
-function cmdUpdate(args: Args, forcedStatus?: Status): void {
+function cmdUpdate(args: Args): void {
   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))
   } else {
@@ -491,7 +628,158 @@ function cmdUpdate(args: Args, forcedStatus?: Status): void {
 function cmdMove(args: Args): void {
   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: Args): void {
+  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: Args): void {
+  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: Args): void {
+  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: Args): void {
+  let entries: InboxEntry[]
+  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: string): string => {
+    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: Args): void {
@@ -523,9 +811,9 @@ function cmdLink(args: Args, action: "link" | "unlink"): void {
   const store = openStoreFor(ref)
   const relation = blocks ? "blocks" : "blocked_by"
   const target = parseRefOn(store, (blocks ?? blockedBy)!)
-  const number = store.parseId(ref)
+  const key = store.parseId(ref)
   const task =
-    action === "link" ? store.link(number, relation, target) : store.unlink(number, relation, target)
+    action === "link" ? store.link(key, relation, target) : store.unlink(key, relation, target)
   if (args.flags.json) {
     console.log(JSON.stringify({ task }, null, 2))
   } else {
@@ -538,35 +826,77 @@ function cmdLink(args: Args, action: "link" | "unlink"): void {
   }
 }
 
+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: Args): void {
   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: { task: Task; branch: string; base: string }): void => {
+    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))
-      } else if (!result.remote && !result.local) {
-        console.log(`${store.displayId(number)} wasn't claimed — no ${result.branch} to delete`)
+        console.log(JSON.stringify({ released: result, comment }, null, 2))
+      } 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) {
       console.error(`error: ${error.message}`)
@@ -576,6 +906,164 @@ function cmdClaim(args: Args): void {
   }
 }
 
+/** `task instructions` — the shipped agent conventions, self-served at runtime. */
+function cmdInstructions(): void {
+  // 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: Args): void {
+  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: Args): void {
+  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 = (): string => {
+    const slug = rest[0]
+    if (!slug) fail(`usage: task goal ${sub} <slug>`)
+    return slug
+  }
+  const printGoal = (goal: { slug: string; title: string; archived?: boolean }, verb: string) =>
+    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: Record<string, string> = {
   flag: "--author",
   env: "$TASK_AUTHOR",
@@ -594,36 +1082,51 @@ function cmdWhoami(args: Args): void {
 }
 
 /**
- * `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: Args): void {
-  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: Args): void {
+  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: Args): void {
   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)}`)
 }
 
 /**
@@ -818,51 +1321,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
@@ -880,19 +1474,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 →
@@ -923,22 +1520,34 @@ function main(): void | Promise<void> {
       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":
@@ -951,8 +1560,8 @@ function main(): void | Promise<void> {
       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":