@nickmeriano/task 0.8.0 → 0.10.0

package/dist/cli.js

@@ -6,15 +6,17 @@
 //   task init
 //   task add "Wire up webhooks" --tags api,infra --goal launch
 //   task list --status todo,in_progress
-//   task move TAS-3 done
+//   task move TAS-x7k4m done
 //   task serve
 import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import { basename, join, relative, sep } from "node:path";
 import process from "node:process";
 import { resolveAuthor } from "./author.js";
 import { checkBoards, checkRoot } from "./check.js";
-import { ClaimError, claim, claimNext, claimableTasks, promote, release, selectionBoards, } from "./claim.js";
+import { ClaimError, claim, claimLockOnly, claimNext, claimableTasks, promote, release, selectionBoards, sweep, } from "./claim.js";
+import { addAskRouted, setAskResolvedRouted } from "./claim-io.js";
+import { buildInbox } from "./inbox.js";
 import { STALE_DAYS, buildOverview } from "./overview.js";
 import { searchStore } from "./search.js";
 import { detectRepo, parseSlug, publish, resolveHost } from "./publish.js";
@@ -45,7 +47,6 @@ const BOOLEAN_FLAGS = new Set([
     "version",
     "yes",
     "needs-human",
-    "no-needs-human",
     "archived",
     "claimable",
     "release",
@@ -58,6 +59,8 @@ const BOOLEAN_FLAGS = new Set([
     "fix",
     "next",
     "force",
+    "reopen",
+    "lock-only",
 ]);
 /**
  * Value flags that may repeat — `--board NIC --board TAS` accumulates in
@@ -65,14 +68,26 @@ const BOOLEAN_FLAGS = new Set([
  * last-one-wins.
  */
 const REPEATABLE_FLAGS = new Set(["board"]);
+/**
+ * Repeatable flags whose values are free text — collected verbatim into a
+ * list, never comma-joined, because an ask like "check A, then B" must
+ * survive as one ask.
+ */
+const MULTI_FLAGS = new Set(["ask"]);
 function parseArgs(argv) {
     const positional = [];
     const flags = {};
+    const multi = {};
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg.startsWith("--")) {
             const name = arg.slice(2);
             const set = (key, value) => {
+                if (MULTI_FLAGS.has(key)) {
+                    ;
+                    (multi[key] ??= []).push(value);
+                    return;
+                }
                 const prior = flags[key];
                 flags[key] =
                     REPEATABLE_FLAGS.has(key) && typeof prior === "string" ? `${prior},${value}` : value;
@@ -92,7 +107,7 @@ function parseArgs(argv) {
             positional.push(arg);
         }
     }
-    return { positional, flags };
+    return { positional, flags, multi };
 }
 function str(flags, name) {
     const v = flags[name];
@@ -108,18 +123,18 @@ function openStore() {
         fail("no .task directory found in this directory or any parent — run `task init` first");
     return openBoard(root);
 }
-/** The prefix a ref carries, if any: "TAS-12" → "TAS", "12" → null. */
+/** The prefix a ref carries, if any: "TAS-x7k4m" → "TAS", "x7k4m" → null. */
 function refPrefix(ref) {
-    const match = /^([A-Za-z0-9]+)-\d+$/.exec(ref.trim());
+    const match = /^([A-Za-z0-9]+)-[A-Za-z0-9]+$/.exec(ref.trim());
     return match ? match[1].toUpperCase() : null;
 }
 /**
- * The board a ref belongs to. A bare number means the nearest board, as ever —
+ * The board a ref belongs to. A bare key means the nearest board, as ever —
  * but a prefixed id is an address, and it routes: if the prefix isn't the
  * nearest board's, every board in the repo (walking up to the outermost board
- * root, then down) is searched for it, so `task show TAS-12` works from
+ * root, then down) is searched for it, so `task show TAS-x7k4m` works from
  * anywhere in a monorepo. What this must never do is what it used to: silently
- * strip a foreign prefix and act on the nearest board's ticket of that number.
+ * strip a foreign prefix and act on the nearest board's ticket of that key.
  */
 function openStoreFor(ref) {
     const prefix = ref ? refPrefix(ref) : null;
@@ -205,10 +220,6 @@ function patchFromFlags(flags) {
     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
     // because appending needs the task's current list.
     const prs = str(flags, "prs");
@@ -268,18 +279,27 @@ function cmdInit(args) {
 function cmdAdd(args) {
     const title = args.positional.join(" ").trim();
     if (!title)
-        fail(`usage: task add <title> [--description …] [--status …] [--tags a,b] [--goal <slug>] [--needs-human]`);
+        fail(`usage: task add <title> [--description …] [--status …] [--tags a,b] [--goal <slug>] [--ask "<text>"]…`);
     const store = openStore();
     const patch = patchFromFlags(args.flags);
     const pr = str(args.flags, "pr");
     if (pr)
         patch.prs = [...(patch.prs ?? []), pr];
-    const task = store.create({ title, ...patch });
+    let task = store.create({ title, ...patch });
+    const asks = (args.multi.ask ?? []).map((a) => a.trim()).filter(Boolean);
+    if (asks.length > 0) {
+        const author = resolveAuthor(str(args.flags, "author")).name;
+        for (const text of asks)
+            store.addAsk(task.key, text, author);
+        task = store.get(task.key);
+    }
     if (args.flags.json) {
         console.log(JSON.stringify({ task }, null, 2));
     }
     else {
         printTask(task);
+        for (const ask of task.asks)
+            console.log(`  ask [${ask.ordinal}] ${ask.text.split("\n")[0]}`);
     }
 }
 /** `--board NIC --board TAS` (or `--board NIC,TAS`) → ["NIC", "TAS"]. */
@@ -460,7 +480,7 @@ function cmdArchive(args) {
     }
     const store = openStore();
     const finished = store.list({ statuses: ["done", "canceled"] });
-    const archived = finished.map((t) => store.archive(t.number));
+    const archived = finished.map((t) => store.archive(t.key));
     if (args.flags.json) {
         console.log(JSON.stringify({ archived }, null, 2));
     }
@@ -490,11 +510,11 @@ function cmdShow(args) {
     if (!ref)
         fail("usage: task show <id>");
     const store = openStoreFor(ref);
-    const number = store.parseId(ref);
-    const task = store.get(number);
+    const key = store.parseId(ref);
+    const task = store.get(key);
     if (!task)
-        fail(`no such task: ${store.displayId(number)}`);
-    const comments = store.comments(number);
+        fail(`no such task: ${store.displayId(key)}`);
+    const comments = store.comments(key);
     // The goal rides along in full — title *and* description — so an agent
     // picking the ticket up cold inherits the shared context without it being
     // pasted into every ticket. null when unset or when the ref dangles.
@@ -504,18 +524,27 @@ function cmdShow(args) {
         return;
     }
     // A linked task is only as useful as knowing whether it's still in the way.
-    const describeLinks = (numbers) => numbers
-        .map((n) => {
-        const other = store.get(n);
-        return other ? `${other.id} (${other.status})` : store.displayId(n);
+    const describeLinks = (keys) => keys
+        .map((k) => {
+        const other = store.get(k);
+        return other ? `${other.id} (${other.status})` : store.displayId(k);
     })
         .join(", ");
     console.log(`${task.id}  ${task.title}`);
     console.log(`status    ${task.status}`);
     if (task.archived)
         console.log(`archived  yes — \`task unarchive ${task.id}\` to edit`);
-    if (task.needsHuman)
-        console.log(`needs     a human`);
+    const openAsks = task.asks.filter((a) => !a.resolvedAt);
+    if (openAsks.length) {
+        console.log(`needs     a human — ${openAsks.length} open ask${openAsks.length === 1 ? "" : "s"}`);
+    }
+    for (const ask of task.asks) {
+        const state = ask.resolvedAt
+            ? `✓ resolved${ask.resolvedBy ? ` by ${ask.resolvedBy}` : ""}`
+            : `○ open${ask.author ? ` · ${ask.author}` : ""} · ${ask.createdAt.slice(0, 10)}`;
+        console.log(`ask [${ask.ordinal}]   ${ask.text.split("\n").join("\n          ")}`);
+        console.log(`          ${state}`);
+    }
     if (task.tags.length)
         console.log(`tags      ${task.tags.join(", ")}`);
     if (task.goal) {
@@ -548,17 +577,17 @@ function cmdUpdate(args) {
     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);
     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));
     }
@@ -570,7 +599,7 @@ function cmdMove(args) {
     const [ref, status] = args.positional;
     if (!ref || !status)
         fail("usage: task move <id> <status>");
-    cmdUpdate({ positional: [ref], flags: { ...args.flags, status } });
+    cmdUpdate({ positional: [ref], flags: { ...args.flags, status }, multi: {} });
 }
 /**
  * `task promote <id>` — backlog → todo, the human "build this" call; see
@@ -602,6 +631,121 @@ function cmdPromote(args) {
         throw error;
     }
 }
+/**
+ * `task ask <id> <text>` — file one thing a person owes this ticket. The ask
+ * is the primitive every human requirement funnels through: it derives the
+ * needs-human badge, feeds `task inbox`, and gates `done` until resolved.
+ * On a claimed ticket the write lands on the claim branch as a pushed commit
+ * (see claim-io.ts) — the worker's done gate has to see debt filed mid-claim.
+ */
+function cmdAsk(args) {
+    const [ref, ...rest] = args.positional;
+    const text = rest.join(" ").trim();
+    if (!ref || !text)
+        fail(`usage: task ask <id> "<what a person needs to do>" [--author <who>]`);
+    const store = openStoreFor(ref);
+    const author = resolveAuthor(str(args.flags, "author")).name;
+    const { ask, branch } = addAskRouted(store, store.parseId(ref), text, author);
+    if (args.flags.json) {
+        console.log(JSON.stringify({ ask, branch }, null, 2));
+    }
+    else {
+        console.log(`asked on ${ask.taskId} [${ask.ordinal}]  ${ask.text.split("\n")[0]}`);
+        if (branch)
+            console.log(`committed and pushed to ${branch} — the claim owns this ticket's asks`);
+    }
+}
+/**
+ * `task resolve <id> <n>` — check an ask off (`--reopen` puts it back). The
+ * ordinal is the one `task show` prints; the optional --comment lands as an
+ * attributed comment so the answer travels with the ticket, not just the
+ * checkbox. Resolving the last open ask is the moment a ticket usually moves
+ * to done — the hint below says so rather than doing it, because finishing a
+ * ticket is a statement about the *work*, not the asks.
+ */
+function cmdResolve(args) {
+    const [ref, askRef] = args.positional;
+    if (!ref || !askRef) {
+        fail('usage: task resolve <id> <ordinal> [--comment "<note>"] [--reopen] [--author <who>]');
+    }
+    const store = openStoreFor(ref);
+    const key = store.parseId(ref);
+    const author = resolveAuthor(str(args.flags, "author")).name;
+    const { ask, branch } = setAskResolvedRouted(store, key, askRef, !args.flags.reopen, author);
+    const note = str(args.flags, "comment")?.trim();
+    const comment = note
+        ? store.addComment(key, `${args.flags.reopen ? "Reopened" : "Resolved"} ask [${ask.ordinal}] (${ask.text.split("\n")[0]}): ${note}`, author)
+        : null;
+    const task = store.get(key);
+    // Branch-resolved asks aren't in the local files — count what's still open
+    // on the side that was just written.
+    const remaining = branch
+        ? undefined
+        : task.asks.filter((a) => !a.resolvedAt).length;
+    if (args.flags.json) {
+        console.log(JSON.stringify({ ask, branch, comment, openAsks: remaining ?? null }, null, 2));
+        return;
+    }
+    const verb = args.flags.reopen ? "reopened" : "resolved";
+    console.log(`${verb} ${ask.taskId} [${ask.ordinal}]  ${ask.text.split("\n")[0]}`);
+    if (branch) {
+        console.log(`committed and pushed to ${branch} — the worker sees it on its next pull`);
+        return;
+    }
+    if (args.flags.reopen)
+        return;
+    if (remaining !== undefined && remaining > 0) {
+        console.log(`${remaining} ask${remaining === 1 ? "" : "s"} still open on ${ask.taskId}`);
+    }
+    else if (task.status === "in_progress") {
+        console.log(`that was the last open ask — \`task move ${ask.taskId} done\` if the work is finished too`);
+    }
+}
+/**
+ * `task inbox` — what do I need to do NOW to unblock work: every open ask on
+ * effectively-in-progress tickets (file status, or a live claim branch —
+ * see inbox.ts), across the repo's boards, oldest owed first. Deliberately
+ * cross-board, like `claim --next`: the queue's attention is per-board, a
+ * person's isn't.
+ */
+function cmdInbox(args) {
+    let entries;
+    try {
+        const scope = findScopeRoot(process.cwd());
+        const boards = selectionBoards(process.cwd(), boardFlag(args)).map((store) => {
+            const rel = relative(scope, store.root).split(sep).join("/");
+            return { id: rel === "" ? "." : rel, store };
+        });
+        entries = buildInbox(boards);
+    }
+    catch (error) {
+        if (error instanceof ClaimError)
+            fail(error.message);
+        throw error;
+    }
+    if (args.flags.json) {
+        console.log(JSON.stringify({ inbox: entries }, null, 2));
+        return;
+    }
+    if (entries.length === 0) {
+        console.log("inbox zero — no open asks on in-progress work");
+        return;
+    }
+    const open = entries.reduce((sum, e) => sum + e.asks.length, 0);
+    console.log(`${open} open ask${open === 1 ? "" : "s"} across ${entries.length} ticket${entries.length === 1 ? "" : "s"}`);
+    const age = (iso) => {
+        const days = Math.floor((Date.now() - Date.parse(iso)) / 86_400_000);
+        return days > 0 ? `${days}d` : "today";
+    };
+    for (const entry of entries) {
+        const via = entry.claim ? `  (claimed: ${entry.claim.branch})` : "";
+        console.log(`\n${entry.task.id}  ${entry.task.title}${via}`);
+        for (const ask of entry.asks) {
+            const who = ask.author ? ` · ${ask.author}` : "";
+            console.log(`  [${ask.ordinal}] ${ask.text.split("\n")[0]}  (${age(ask.createdAt)}${who})`);
+        }
+    }
+}
 function cmdComment(args) {
     const [ref, ...rest] = args.positional;
     const body = rest.join(" ").trim();
@@ -632,8 +776,8 @@ function cmdLink(args, action) {
     const store = openStoreFor(ref);
     const relation = blocks ? "blocks" : "blocked_by";
     const target = parseRefOn(store, (blocks ?? blockedBy));
-    const number = store.parseId(ref);
-    const task = action === "link" ? store.link(number, relation, target) : store.unlink(number, relation, target);
+    const key = store.parseId(ref);
+    const task = action === "link" ? store.link(key, relation, target) : store.unlink(key, relation, target);
     if (args.flags.json) {
         console.log(JSON.stringify({ task }, null, 2));
     }
@@ -645,7 +789,7 @@ 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>"';
+const CLAIM_USAGE = 'usage: task claim <id> [--lock-only] | task claim --next | task claim --release <id> --comment "<why>"';
 /**
  * `task claim <id>` / `task claim --next` / `task claim --release <id>` — see
  * claim.ts for the mechanics. Exit codes are the contract callers script
@@ -661,6 +805,14 @@ function cmdClaim(args) {
         }
         else {
             console.log(`claimed ${result.task.id} — on ${result.branch} (from ${result.base}), status in_progress`);
+            // The backstop for branch-pinned sessions: a harness that assigned this
+            // checkout a branch expects the work to land there, and a plain claim
+            // just moved HEAD somewhere else. The skill carries the rule; this line
+            // is for the worker that hasn't read it.
+            const defaultLocal = result.base.replace(/^origin\//, "");
+            if (result.previous !== defaultLocal && result.previous !== result.branch) {
+                console.log(`note: this moved you off ${result.previous} — if your work must deliver on ${result.previous}, \`task claim --release ${result.task.id} --comment "…"\` and re-claim with --lock-only`);
+            }
         }
     };
     try {
@@ -670,7 +822,7 @@ function cmdClaim(args) {
             // retrying past lost races internally.
             if (ref)
                 fail("pass an id or --next, not both");
-            if (args.flags.release)
+            if (args.flags.release || args.flags["lock-only"])
                 fail(CLAIM_USAGE);
             const result = claimNext(selectionBoards(process.cwd(), boardFlag(args)), options);
             if (!result) {
@@ -688,7 +840,23 @@ function cmdClaim(args) {
         if (!ref)
             fail(CLAIM_USAGE);
         const store = openStoreFor(ref);
-        const number = store.parseId(ref);
+        const key = store.parseId(ref);
+        if (args.flags["lock-only"]) {
+            // The branch-pinned session's claim: same lock, no checkout switch —
+            // the work delivers on the branch this session was handed, and the flip
+            // commit's delivered_by: trailer says so. See claimLockOnly.
+            if (args.flags.release)
+                fail(CLAIM_USAGE);
+            const result = claimLockOnly(store, key, options);
+            if (args.flags.json) {
+                console.log(JSON.stringify({ task: result.task, branch: result.branch, deliveredBy: result.deliveredBy }, null, 2));
+            }
+            else {
+                console.log(`claimed ${result.task.id} — ${result.branch} on origin (lock only, from ${result.base}), status in_progress`);
+                console.log(`checkout untouched — keep working on ${result.deliveredBy} (recorded as delivered_by in the claim commit)`);
+            }
+            return;
+        }
         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
@@ -697,28 +865,28 @@ function cmdClaim(args) {
             if (!why) {
                 fail('task claim --release requires --comment "<why>" — the next worker inherits what was tried');
             }
-            const result = release(store, number);
+            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(number, why, resolveAuthor(str(args.flags, "author")).name)
+                ? store.addComment(key, why, resolveAuthor(str(args.flags, "author")).name)
                 : null;
             if (args.flags.json) {
                 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`);
+                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(`left the reason as a comment on ${store.displayId(number)} — uncommitted, commit it with your next change`);
+                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;
         }
-        printClaim(claim(store, number, options));
+        printClaim(claim(store, key, options));
     }
     catch (error) {
         if (error instanceof ClaimError) {
@@ -728,6 +896,48 @@ function cmdClaim(args) {
         throw error;
     }
 }
+/**
+ * `task sweep` — the janitor: delete every claim branch on origin whose ticket
+ * is done, canceled, or missing on the current checkout. Zero judgment on
+ * purpose — the trigger belongs to a runner (CI on push-to-main or cron), not
+ * an agent. Exit codes: 0 clean (including nothing to do), 1 a deletion was
+ * attempted and failed — a failing sweep means this runner can't delete
+ * branches either, which is worth an alert.
+ */
+function cmdSweep(args) {
+    try {
+        const result = sweep(process.cwd());
+        if (args.flags.json) {
+            console.log(JSON.stringify({ sweep: result }, null, 2));
+        }
+        else {
+            for (const entry of result.swept) {
+                console.log(`swept ${entry.branch} — ${entry.reason === "missing" ? `no ticket ${entry.ticket}` : `${entry.ticket} is ${entry.reason}`}`);
+            }
+            for (const entry of result.kept) {
+                console.log(`kept ${entry.branch} — ${entry.ticket} is ${entry.status}`);
+            }
+            for (const branch of result.skipped) {
+                console.log(`skipped ${branch} — not a name \`task claim\` mints (foreign or pre-migration); delete it by hand if it's stale`);
+            }
+            for (const entry of result.failed) {
+                console.error(`error: couldn't delete ${entry.branch} — ${entry.error}`);
+            }
+            if (!result.swept.length && !result.kept.length && !result.skipped.length && !result.failed.length) {
+                console.log("no claim branches on origin — nothing to sweep");
+            }
+        }
+        if (result.failed.length)
+            process.exit(1);
+    }
+    catch (error) {
+        if (error instanceof ClaimError) {
+            console.error(`error: ${error.message}`);
+            process.exit(2);
+        }
+        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
@@ -746,7 +956,10 @@ function cmdOverview(args) {
     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}`);
+    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) => [
@@ -946,9 +1159,9 @@ function cmdDelete(args) {
     if (!ref)
         fail("usage: task delete <id>");
     const store = openStoreFor(ref);
-    const number = store.parseId(ref);
-    store.delete(number);
-    console.log(`deleted ${store.displayId(number)}`);
+    const key = store.parseId(ref);
+    store.delete(key);
+    console.log(`deleted ${store.displayId(key)}`);
 }
 /**
  * Bind the first free port at or after `first`, the way dev servers do: a board
@@ -1127,11 +1340,14 @@ subdirectory (it walks up to find .task/, like git).
 Usage
   task init [--name <name>] [--prefix <PREFIX>]
   task add <title> [--description <text> | --description-file <path|->]
-                   [--status <s>] [--tags <a,b>] [--goal <slug>] [--needs-human]
+                   [--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
+                                (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 search <query> [--status <s1,s2>] [--tag <a,b>] [--goal <slug>]
@@ -1145,18 +1361,38 @@ Usage
                                 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>       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
+                                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 / needs-human tickets still
-                                promote — those are claim-time gates, reported
-                                as a note — so promoting can queue work behind
+                                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>
@@ -1164,7 +1400,7 @@ Usage
                                 both tasks (A blocked by B ⇔ B blocks A)
   task unlink <id> (--blocks <id> | --blocked-by <id>)
   task claim <id> [--force]     claim a ticket before working it: branch
-                                <branchPrefix><prefix>-<n> off origin's
+                                <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
@@ -1177,8 +1413,21 @@ Usage
                                 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,
-                                at the cap)
+                                (not todo, blocked, dirty tree, at the cap)
+  task claim <id> --lock-only [--force]
+                                take the lock without touching the checkout:
+                                the in_progress flip commit is built against
+                                origin's default branch in a temporary index
+                                and pushed as the claim branch — same atomic
+                                lock, same exit codes, but HEAD, the working
+                                tree and the index stay exactly where they
+                                are (dirty is fine). For sessions pinned to
+                                a provisioned branch (CI, a Claude web
+                                session): the lock lives on the claim
+                                branch, the work delivers on yours, and the
+                                flip commit's delivered_by: trailer records
+                                which. --release works on a lock-only claim
+                                the same way
   task claim --next [--board <P>] [--force]
                                 claim the top claimable ticket in one call,
                                 retrying past lost races internally — the
@@ -1194,18 +1443,36 @@ Usage
                                 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
+                                so the next worker inherits what was tried.
+                                The deletion is verified with ls-remote: an
+                                environment that silently drops deletion
+                                pushes fails loudly instead of reporting a
+                                release that didn't happen
+  task sweep                    the janitor: delete every claim branch on
+                                origin whose ticket is done, canceled, or
+                                missing on the current checkout, across all
+                                the repo's boards. Scoped to names \`claim\`
+                                mints (<prefix>-<valid key>): anything else
+                                under the namespace — pre-migration numeric
+                                claims, hand-made branches — is reported and
+                                left alone, since it may be an open PR's
+                                head. Pure git, zero judgment — run it from
+                                a runner that can delete remote branches (CI
+                                on push-to-main or cron) to heal stale
+                                claims left by environments that can't.
+                                Prints swept/kept/skipped; exits non-zero if
+                                a deletion was attempted and failed
   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. Same
-                                board scope as claim --next
+                                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
-                                needs-human counts, stale tickets (untouched
+                                open-ask counts, stale tickets (untouched
                                 ${STALE_DAYS}+ days), oldest open ticket
   task comment <id> <text> [--author <who>]
   task delete <id>
@@ -1227,7 +1494,7 @@ Usage
   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
@@ -1259,15 +1526,18 @@ Usage
                                 tasks — those are in .task/ either way
 
 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
   --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
+  --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, --goal "" clears it, --prs ""
                 detaches all PRs
@@ -1313,8 +1583,16 @@ function main() {
             return cmdLink(args, "unlink");
         case "claim":
             return cmdClaim(args);
+        case "sweep":
+            return cmdSweep(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":