@nickmeriano/task 0.7.0 → 0.8.0

package/src/cli.ts

@@ -1,13 +1,12 @@
 #!/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-3 done
 //   task serve
 
 import { spawn } from "node:child_process"
@@ -16,10 +15,21 @@ import type { Server } from "node:http"
 import { basename, join } 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 { 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 +42,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
@@ -84,8 +87,18 @@ const BOOLEAN_FLAGS = new Set([
   "public",
   "private",
   "no-wait",
+  "fix",
+  "next",
+  "force",
 ])
 
+/**
+ * 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"])
+
 function parseArgs(argv: string[]): Args {
   const positional: string[] = []
   const flags: Record<string, string | boolean> = {}
@@ -93,13 +106,18 @@ function parseArgs(argv: string[]): Args {
     const arg = argv[i]
     if (arg.startsWith("--")) {
       const name = arg.slice(2)
+      const set = (key: string, value: string): void => {
+        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)
@@ -199,13 +217,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
+  const goal = str(flags, "goal")
+  if (goal !== undefined) patch.goal = goal.trim() || null
   if (flags["needs-human"]) patch.needsHuman = true
   if (flags["no-needs-human"]) patch.needsHuman = false
   // Replace semantics like --tags; `--pr` (append one) is handled per-command
@@ -241,7 +273,7 @@ function taskRow(t: Task): string[] {
     t.needsHuman ? "⚑" : "",
     t.title,
     t.tags.join(","),
-    t.milestone ?? "",
+    t.goal ?? "",
   ]
 }
 
@@ -272,7 +304,7 @@ 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>] [--needs-human]`)
   const store = openStore()
   const patch = patchFromFlags(args.flags)
   const pr = str(args.flags, "pr")
@@ -285,15 +317,31 @@ function cmdAdd(args: Args): void {
   }
 }
 
+/** `--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 +351,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 +366,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 +388,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
@@ -433,8 +530,12 @@ function cmdShow(args: Args): void {
   const task = store.get(number)
   if (!task) fail(`no such task: ${store.displayId(number)}`)
   const comments = store.comments(number)
+  // 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.
@@ -450,13 +551,19 @@ function cmdShow(args: Args): void {
   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.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,13 +573,12 @@ 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 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".
@@ -494,6 +600,34 @@ function cmdMove(args: Args): void {
   cmdUpdate({ positional: [ref], flags: { ...args.flags, status } })
 }
 
+/**
+ * `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
+  }
+}
+
 function cmdComment(args: Args): void {
   const [ref, ...rest] = args.positional
   const body = rest.join(" ").trim()
@@ -538,35 +672,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 number = store.parseId(ref)
     if (args.flags.release) {
+      // 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, number)
+      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(number, 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(JSON.stringify({ released: result, comment }, null, 2))
+      } else if (!commented) {
         console.log(`${store.displayId(number)} 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(`left the reason as a comment on ${store.displayId(number)} — 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, number, options))
   } catch (error) {
     if (error instanceof ClaimError) {
       console.error(`error: ${error.message}`)
@@ -576,6 +752,161 @@ 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(", ")})` : ""}`
+  console.log(`  ${claimed}   needs-human ${overview.needsHuman}`)
+  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,27 +925,42 @@ 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 {
@@ -818,42 +1164,102 @@ 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>] [--needs-human]
+                                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
+  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>]
+  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>]
                    [--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 move <id> <status>       change a ticket's status — the one general
+                                status API (backlog todo in_progress done
+                                canceled). The named verbs below exist only
+                                where a transition does more than write the
+                                status field
+  task promote <id>             backlog → todo, the human "build this" call.
+                                No quality gate — planning happens at claim
+                                time. Blocked / needs-human tickets still
+                                promote — those 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>-<n> 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, needs-human, 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
+                                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 / needs-human / already
-                                claimed on origin. Top entry is next up
+                                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
+                                needs-human 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/,
@@ -863,6 +1269,15 @@ Usage
   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,9 +1295,6 @@ 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
@@ -890,9 +1302,12 @@ Values
                 prefix, so TAS-12 works from anywhere in a monorepo
   status        ${STATUSES.join("  ")}
   --tag a,b     matches a task carrying *either* tag
+  --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 this can't be finished by an agent alone
   --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 +1338,28 @@ 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 "overview":
+      return cmdOverview(args)
+    case "goal":
+      return cmdGoal(args)
     case "comment":
       return cmdComment(args)
     case "whoami":
@@ -951,8 +1372,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":