@nickmeriano/task 0.7.0 → 0.8.0

package/dist/cli.js

@@ -1,32 +1,27 @@
 #!/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";
 import { readFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import process from "node:process";
 import { resolveAuthor } from "./author.js";
-import { ClaimError, claim, claimableTasks, release } from "./claim.js";
+import { checkBoards, checkRoot } from "./check.js";
+import { ClaimError, claim, claimNext, claimableTasks, promote, release, selectionBoards, } from "./claim.js";
+import { STALE_DAYS, buildOverview } from "./overview.js";
+import { searchStore } from "./search.js";
 import { detectRepo, parseSlug, publish, resolveHost } from "./publish.js";
 import { createTaskServer } from "./server.js";
-import { initProject, migrateBoard, openBoard } from "./file-store.js";
+import { initProject, openBoard } from "./file-store.js";
 import { CONFIG_FILE, TASK_DIR, boardConfig, findBoards, findBoardsByPrefix, findRoot, findScopeRoot, } from "./store.js";
 import { STATUSES, isStatus } from "./types.js";
-// node:sqlite still emits an ExperimentalWarning on Node 22 — noise in a CLI
-// that runs it on every invocation. Filter that one warning, keep the rest.
-process.removeAllListeners("warning");
-process.on("warning", (warning) => {
-    if (warning.name !== "ExperimentalWarning")
-        console.error(warning);
-});
 /**
  * Read from package.json rather than duplicated as a literal. Releases here are
  * cut by changesets, which bumps package.json and nothing else — so a hardcoded
@@ -60,7 +55,16 @@ 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) {
     const positional = [];
     const flags = {};
@@ -68,15 +72,20 @@ function parseArgs(argv) {
         const arg = argv[i];
         if (arg.startsWith("--")) {
             const name = arg.slice(2);
+            const set = (key, value) => {
+                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 {
@@ -170,17 +179,32 @@ function patchFromFlags(flags) {
     if (title !== undefined)
         patch.title = title;
     const description = str(flags, "description") ?? str(flags, "desc");
+    // Long markdown doesn't survive shell quoting — `--description-file` keeps
+    // agents writing plans and specs on the CLI path instead of hand-editing
+    // ticket files. `-` reads stdin.
+    const descriptionFile = str(flags, "description-file");
+    if (description !== undefined && descriptionFile !== undefined) {
+        fail("pass --description or --description-file, not both");
+    }
     if (description !== undefined)
         patch.description = description;
+    if (descriptionFile !== undefined) {
+        try {
+            patch.description = readFileSync(descriptionFile === "-" ? 0 : descriptionFile, "utf8");
+        }
+        catch {
+            fail(`--description-file: can't read ${descriptionFile === "-" ? "stdin" : descriptionFile}`);
+        }
+    }
     const status = str(flags, "status");
     if (status !== undefined)
         patch.status = parseStatus(status);
     const tags = str(flags, "tags") ?? str(flags, "tag");
     if (tags !== undefined)
         patch.tags = parseTags(tags);
-    const milestone = str(flags, "milestone");
-    if (milestone !== undefined)
-        patch.milestone = milestone.trim() || null;
+    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"])
@@ -216,7 +240,7 @@ function taskRow(t) {
         t.needsHuman ? "⚑" : "",
         t.title,
         t.tags.join(","),
-        t.milestone ?? "",
+        t.goal ?? "",
     ];
 }
 function printTask(t) {
@@ -244,7 +268,7 @@ function cmdInit(args) {
 function cmdAdd(args) {
     const title = args.positional.join(" ").trim();
     if (!title)
-        fail(`usage: task add <title> [--description …] [--status …] [--tags a,b] [--milestone …] [--needs-human]`);
+        fail(`usage: task add <title> [--description …] [--status …] [--tags a,b] [--goal <slug>] [--needs-human]`);
     const store = openStore();
     const patch = patchFromFlags(args.flags);
     const pr = str(args.flags, "pr");
@@ -258,8 +282,17 @@ function cmdAdd(args) {
         printTask(task);
     }
 }
+/** `--board NIC --board TAS` (or `--board NIC,TAS`) → ["NIC", "TAS"]. */
+function boardFlag(args) {
+    const raw = str(args.flags, "board");
+    if (raw === undefined)
+        return undefined;
+    const prefixes = raw.split(",").map((p) => p.trim()).filter(Boolean);
+    if (prefixes.length === 0)
+        fail("--board needs a prefix, e.g. --board TAS");
+    return prefixes;
+}
 function cmdList(args) {
-    const store = openStore();
     if (args.flags.claimable) {
         // The dispatcher's queue view (TAS-21): claimable already pins the status
         // set and consults origin, so the board-shaping flags don't compose.
@@ -267,7 +300,17 @@ function cmdList(args) {
             if (args.flags[flag] !== undefined)
                 fail(`--claimable can't be combined with --${flag}`);
         }
-        const tasks = claimableTasks(store);
+        // Selection scope, same resolution as `claim --next`: --board flag > root
+        // board's `boards` list > nearest board. Board order is priority order.
+        let tasks;
+        try {
+            tasks = selectionBoards(process.cwd(), boardFlag(args)).flatMap((s) => claimableTasks(s));
+        }
+        catch (error) {
+            if (error instanceof ClaimError)
+                fail(error.message);
+            throw error;
+        }
         if (args.flags.json) {
             console.log(JSON.stringify({ tasks }, null, 2));
         }
@@ -279,6 +322,9 @@ function cmdList(args) {
         }
         return;
     }
+    if (args.flags.board !== undefined)
+        fail("--board only applies to list --claimable");
+    const store = openStore();
     const archived = Boolean(args.flags.archived);
     const statusFlag = str(args.flags, "status");
     const statuses = statusFlag
@@ -292,7 +338,7 @@ function cmdList(args) {
     const tasks = store.list({
         statuses,
         tags: tagFlag ? parseTags(tagFlag) : undefined,
-        milestone: str(args.flags, "milestone"),
+        goal: str(args.flags, "goal"),
         needsHuman: args.flags["needs-human"] ? true : undefined,
         archived: archived || undefined,
     });
@@ -313,6 +359,43 @@ function cmdList(args) {
         table(tasks.map(taskRow));
     }
 }
+/**
+ * `task search <query>` — find tickets by what they say. Case-insensitive
+ * substring over titles, descriptions and comments, scoped by the usual list
+ * filters; `--archived` searches the archive *in addition to* the board (a
+ * search is a question about everything ever written down, unlike
+ * `list --archived`, which is a view of one place).
+ */
+function cmdSearch(args) {
+    const query = args.positional.join(" ").trim();
+    if (!query) {
+        fail("usage: task search <query> [--status <s1,s2>] [--tag <a,b>] [--goal <slug>] [--needs-human] [--archived]");
+    }
+    const store = openStore();
+    const statusFlag = str(args.flags, "status");
+    const tagFlag = str(args.flags, "tags") ?? str(args.flags, "tag");
+    const results = searchStore(store, query, {
+        statuses: statusFlag ? statusFlag.split(",").map(parseStatus) : undefined,
+        tags: tagFlag ? parseTags(tagFlag) : undefined,
+        goal: str(args.flags, "goal"),
+        needsHuman: args.flags["needs-human"] ? true : undefined,
+    }, Boolean(args.flags.archived));
+    if (args.flags.json) {
+        console.log(JSON.stringify({ query, results }, null, 2));
+        return;
+    }
+    if (results.length === 0) {
+        console.log(`no matches for "${query}"${args.flags.archived ? "" : " (--archived searches the archive too)"}`);
+        return;
+    }
+    for (const { task, matches } of results) {
+        console.log(`${task.id}  ${STATUS_GLYPH[task.status]} ${task.status}${task.archived ? " (archived)" : ""}  ${task.title}`);
+        for (const match of matches) {
+            const label = match.field === "comment" ? `comment${match.author ? ` by ${match.author}` : ""}` : match.field;
+            console.log(`        ${label}: ${match.snippet}`);
+        }
+    }
+}
 /**
  * `task boards` — every board in this repo, found the way `task serve` finds
  * them but anchored at the *outermost* board root, so it answers from anywhere
@@ -412,8 +495,12 @@ function cmdShow(args) {
     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.
@@ -431,8 +518,9 @@ function cmdShow(args) {
         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)
@@ -443,6 +531,10 @@ function cmdShow(args) {
     console.log(`updated   ${task.updatedAt}`);
     if (task.description)
         console.log(`\n${task.description}`);
+    if (goal?.description) {
+        console.log(`\n── goal: ${goal.title} (${goal.slug})`);
+        console.log(goal.description.split("\n").map((line) => `  ${line}`).join("\n"));
+    }
     if (comments.length) {
         console.log(``);
         for (const c of comments) {
@@ -451,15 +543,13 @@ function cmdShow(args) {
         }
     }
 }
-function cmdUpdate(args, forcedStatus) {
+function cmdUpdate(args) {
     const ref = args.positional[0];
     if (!ref)
         fail("usage: task update <id> [--status …] [--title …] …");
     const store = openStoreFor(ref);
     const number = store.parseId(ref);
     const 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".
@@ -482,6 +572,36 @@ function cmdMove(args) {
         fail("usage: task move <id> <status>");
     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) {
+    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) {
     const [ref, ...rest] = args.positional;
     const body = rest.join(" ").trim();
@@ -525,39 +645,80 @@ function cmdLink(args, action) {
         console.log(`${subject} ${verb} blocks ${object}`);
     }
 }
+const CLAIM_USAGE = 'usage: task claim <id> | task claim --next | task claim --release <id> --comment "<why>"';
 /**
- * `task claim <id>` / `task claim --release <id>` — see claim.ts for the
- * mechanics. Exit codes are the contract callers script against: 0 claimed,
- * 1 already claimed (pick the next ticket), 2 not claimable (fix something).
+ * `task claim <id>` / `task claim --next` / `task claim --release <id>` — see
+ * claim.ts for the mechanics. Exit codes are the contract callers script
+ * against: 0 claimed, 1 already claimed / queue empty (nothing to do here —
+ * a scheduled worker stops cleanly), 2 preconditions failed (fix something).
  */
 function cmdClaim(args) {
     const ref = args.positional[0];
-    if (!ref)
-        fail("usage: task claim <id> | task claim --release <id>");
-    const store = openStoreFor(ref);
-    const number = store.parseId(ref);
+    const options = { force: Boolean(args.flags.force) };
+    const printClaim = (result) => {
+        if (args.flags.json) {
+            console.log(JSON.stringify({ task: result.task, branch: result.branch }, null, 2));
+        }
+        else {
+            console.log(`claimed ${result.task.id} — on ${result.branch} (from ${result.base}), status in_progress`);
+        }
+    };
     try {
+        if (args.flags.next) {
+            // The first line of every scheduled worker: claim the top claimable
+            // ticket across the selection scope (--board > root `boards` > nearest),
+            // retrying past lost races internally.
+            if (ref)
+                fail("pass an id or --next, not both");
+            if (args.flags.release)
+                fail(CLAIM_USAGE);
+            const result = claimNext(selectionBoards(process.cwd(), boardFlag(args)), options);
+            if (!result) {
+                if (args.flags.json) {
+                    console.log(JSON.stringify({ task: null }, null, 2));
+                }
+                else {
+                    console.log("nothing claimable — no unblocked, unclaimed todo tickets in scope");
+                }
+                process.exit(1);
+            }
+            printClaim(result);
+            return;
+        }
+        if (!ref)
+            fail(CLAIM_USAGE);
+        const store = openStoreFor(ref);
+        const 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));
+                console.log(JSON.stringify({ released: result, comment }, null, 2));
             }
-            else if (!result.remote && !result.local) {
+            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) {
@@ -567,6 +728,164 @@ function cmdClaim(args) {
         throw error;
     }
 }
+/** `task instructions` — the shipped agent conventions, self-served at runtime. */
+function cmdInstructions() {
+    // skill/ ships in the npm package; `../` from both dist/cli.js and
+    // src/cli.ts is the package root, same trick VERSION uses.
+    process.stdout.write(readFileSync(new URL("../skill/SKILL.md", import.meta.url), "utf8"));
+}
+/** `task overview [--json]` — one screen of board health. See overview.ts. */
+function cmdOverview(args) {
+    const overview = buildOverview(openStore());
+    if (args.flags.json) {
+        console.log(JSON.stringify({ overview }, null, 2));
+        return;
+    }
+    console.log(`${overview.board} (${overview.prefix}) — ${overview.open} open`);
+    console.log(`  ${STATUSES.map((s) => `${STATUS_GLYPH[s]} ${s} ${overview.statuses[s]}`).join("  ")}`);
+    const claimed = overview.claimed === null
+        ? "claimed ? (origin unreachable)"
+        : `claimed ${overview.claimed.length}${overview.claimed.length ? ` (${overview.claimed.join(", ")})` : ""}`;
+    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) {
+    const [sub, ...rest] = args.positional;
+    const usage = "usage: task goal add <title> [--slug <s>] [--description …] | list [--archived] | " +
+        "show <slug> | update <slug> [--title …] [--description …] | archive <slug> | " +
+        "unarchive <slug> | delete <slug>";
+    if (!sub)
+        fail(usage);
+    const store = openStore();
+    const slugArg = () => {
+        const slug = rest[0];
+        if (!slug)
+            fail(`usage: task goal ${sub} <slug>`);
+        return slug;
+    };
+    const printGoal = (goal, verb) => console.log(`${verb} ${goal.slug}  ${goal.title}${goal.archived ? " (archived)" : ""}`);
+    switch (sub) {
+        case "add": {
+            const title = rest.join(" ").trim();
+            if (!title)
+                fail("usage: task goal add <title> [--slug <s>] [--description …]");
+            const goal = store.createGoal({
+                title,
+                slug: str(args.flags, "slug"),
+                description: str(args.flags, "description") ?? str(args.flags, "desc"),
+            });
+            if (args.flags.json)
+                console.log(JSON.stringify({ goal }, null, 2));
+            else
+                printGoal(goal, "created");
+            return;
+        }
+        case "list": {
+            const archived = Boolean(args.flags.archived);
+            const goals = store.goals(archived);
+            // Progress is derived here, at read time — a goal file never stores it.
+            const tasks = store.list({ statuses: undefined });
+            const rows = goals.map((goal) => {
+                const mine = tasks.filter((t) => t.goal === goal.slug);
+                const done = mine.filter((t) => t.status === "done" || t.status === "canceled").length;
+                return { ...goal, open: mine.length - done, done, total: mine.length };
+            });
+            if (args.flags.json) {
+                console.log(JSON.stringify({ goals: rows }, null, 2));
+            }
+            else if (rows.length === 0) {
+                console.log(archived ? "no archived goals" : "no goals — create one with `task goal add`");
+            }
+            else {
+                table(rows.map((g) => [g.slug, g.title, `${g.done}/${g.total} done`]));
+            }
+            return;
+        }
+        case "show": {
+            const slug = slugArg();
+            const goal = store.getGoal(slug);
+            if (!goal)
+                fail(`no such goal: "${slug}"`);
+            const tasks = store.list({ statuses: undefined, goal: slug });
+            if (args.flags.json) {
+                console.log(JSON.stringify({ goal, tasks }, null, 2));
+                return;
+            }
+            console.log(`${goal.slug}  ${goal.title}`);
+            if (goal.archived)
+                console.log(`archived  yes — \`task goal unarchive ${goal.slug}\` to edit`);
+            console.log(`created   ${goal.createdAt}`);
+            console.log(`updated   ${goal.updatedAt}`);
+            if (goal.description)
+                console.log(`\n${goal.description}`);
+            if (tasks.length) {
+                console.log("");
+                table(tasks.map(taskRow));
+            }
+            return;
+        }
+        case "update": {
+            const patch = {
+                ...(str(args.flags, "title") !== undefined && { title: str(args.flags, "title") }),
+                ...((str(args.flags, "description") ?? str(args.flags, "desc")) !== undefined && {
+                    description: str(args.flags, "description") ?? str(args.flags, "desc"),
+                }),
+            };
+            if (Object.keys(patch).length === 0)
+                fail("nothing to update — pass --title or --description");
+            const goal = store.updateGoal(slugArg(), patch);
+            if (args.flags.json)
+                console.log(JSON.stringify({ goal }, null, 2));
+            else
+                printGoal(goal, "updated");
+            return;
+        }
+        case "archive": {
+            const goal = store.archiveGoal(slugArg());
+            if (args.flags.json)
+                console.log(JSON.stringify({ goal }, null, 2));
+            else
+                printGoal(goal, "archived");
+            return;
+        }
+        case "unarchive": {
+            const goal = store.unarchiveGoal(slugArg());
+            if (args.flags.json)
+                console.log(JSON.stringify({ goal }, null, 2));
+            else
+                printGoal(goal, "unarchived");
+            return;
+        }
+        case "delete": {
+            const slug = slugArg();
+            store.deleteGoal(slug);
+            console.log(`deleted goal ${slug}`);
+            return;
+        }
+        default:
+            fail(usage);
+    }
+}
 const AUTHOR_SOURCE = {
     flag: "--author",
     env: "$TASK_AUTHOR",
@@ -584,26 +903,43 @@ function cmdWhoami(args) {
     }
 }
 /**
- * `task migrate` — from the legacy committed SQLite database to text-canonical
- * storage: one markdown file per ticket and per comment under .task/tickets/,
- * with the database left on disk as an ignored backup. Additive and safe to
- * re-run planning-wise: it refuses to run twice.
+ * `task check [--fix]` — lint the board files. Git merges and hand-edits are
+ * write paths no CLI code sees, so validation is a command you can run (and
+ * put in pre-commit or CI, where merge-introduced drift gets caught). Covers
+ * every board at or below here, the same set `task serve` would serve. Exits
+ * non-zero while problems remain; `--fix` first applies the mechanical
+ * repairs — pruning dangling references, rewriting files into canonical form.
  */
-function cmdMigrate(args) {
-    const root = findRoot(process.cwd());
-    if (!root)
-        fail("no .task directory found in this directory or any parent — run `task init` first");
-    const result = migrateBoard(root);
+function cmdCheck(args) {
+    const root = checkRoot(process.cwd());
+    const fix = Boolean(args.flags.fix);
+    const result = checkBoards(root, fix);
+    if (result.boards === 0) {
+        fail("no .task directory found in this directory, any parent, or below — run `task init` first");
+    }
+    // In fix mode the fixable issues were just repaired; what's left needs a human.
+    const remaining = fix ? result.issues.filter((issue) => !issue.fixable) : result.issues;
     if (args.flags.json) {
-        console.log(JSON.stringify({ migrated: result }, null, 2));
-        return;
+        console.log(JSON.stringify({ ...result, remaining }, null, 2));
+    }
+    else {
+        for (const file of result.fixed)
+            console.log(`fixed    ${file}`);
+        for (const issue of remaining) {
+            console.log(`${issue.fixable ? "fixable" : "problem"}  ${issue.file}`);
+            console.log(`         ${issue.message}`);
+        }
+        const scope = `${result.files} file${result.files === 1 ? "" : "s"} across ${result.boards} board${result.boards === 1 ? "" : "s"}`;
+        if (remaining.length === 0) {
+            console.log(result.fixed.length ? `fixed ${result.fixed.length}, ${scope} clean` : `ok — ${scope}`);
+        }
+        else {
+            const fixable = remaining.filter((issue) => issue.fixable).length;
+            console.log(`${remaining.length} problem${remaining.length === 1 ? "" : "s"} in ${scope}${fixable ? ` (${fixable} fixable — run \`task check --fix\`)` : ""}`);
+        }
     }
-    console.log(`Migrated ${result.tasks} task${result.tasks === 1 ? "" : "s"} and ${result.comments} comment${result.comments === 1 ? "" : "s"} to .task/tickets/`);
-    console.log(`tasks.db stays on disk as a backup, but it's ignored now — the files are the state.`);
-    console.log(``);
-    console.log(`Next:`);
-    console.log(`  git rm --cached ${join(TASK_DIR, "tasks.db")}     stop tracking the database`);
-    console.log(`  git add ${TASK_DIR}                       commit the tickets`);
+    if (remaining.length > 0)
+        process.exitCode = 1;
 }
 function cmdDelete(args) {
     const ref = args.positional[0];
@@ -790,42 +1126,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/,
@@ -835,6 +1231,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
@@ -852,9 +1257,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
@@ -862,9 +1264,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 →
@@ -892,22 +1297,28 @@ function main() {
             return cmdAdd(args);
         case "list":
             return cmdList(args);
+        case "search":
+            return cmdSearch(args);
         case "show":
             return cmdShow(args);
         case "update":
             return cmdUpdate(args);
         case "move":
             return cmdMove(args);
-        case "start":
-            return cmdUpdate(args, "in_progress");
-        case "done":
-            return cmdUpdate(args, "done");
+        case "promote":
+            return cmdPromote(args);
         case "link":
             return cmdLink(args, "link");
         case "unlink":
             return cmdLink(args, "unlink");
         case "claim":
             return cmdClaim(args);
+        case "instructions":
+            return cmdInstructions();
+        case "overview":
+            return cmdOverview(args);
+        case "goal":
+            return cmdGoal(args);
         case "comment":
             return cmdComment(args);
         case "whoami":
@@ -920,8 +1331,8 @@ function main() {
             return cmdArchive(args);
         case "unarchive":
             return cmdUnarchive(args);
-        case "migrate":
-            return cmdMigrate(args);
+        case "check":
+            return cmdCheck(args);
         case "serve":
             return cmdServe(args);
         case "publish":