@nickmeriano/task 0.8.0 → 0.10.0

package/src/cli.ts

@@ -6,25 +6,29 @@
 //   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 type { Server } from "node:http"
-import { basename, join } from "node:path"
+import { basename, join, relative, sep } from "node:path"
 import process from "node:process"
 import { resolveAuthor } from "./author.ts"
 import { checkBoards, checkRoot } from "./check.ts"
 import {
   ClaimError,
   claim,
+  claimLockOnly,
   claimNext,
   claimableTasks,
   promote,
   release,
   selectionBoards,
+  sweep,
 } from "./claim.ts"
+import { addAskRouted, setAskResolvedRouted } from "./claim-io.ts"
+import { buildInbox, type InboxEntry } from "./inbox.ts"
 import { STALE_DAYS, buildOverview } from "./overview.ts"
 import { searchStore } from "./search.ts"
 import { detectRepo, parseSlug, publish, resolveHost } from "./publish.ts"
@@ -66,6 +70,8 @@ const PORT_ATTEMPTS = 20
 interface Args {
   positional: string[]
   flags: Record<string, string | boolean>
+  /** Values of MULTI_FLAGS, in given order — e.g. multi.ask from `--ask "…"`. */
+  multi: Record<string, string[]>
 }
 
 // Every valueless flag has to be listed here: an unregistered one swallows the
@@ -77,7 +83,6 @@ const BOOLEAN_FLAGS = new Set([
   "version",
   "yes",
   "needs-human",
-  "no-needs-human",
   "archived",
   "claimable",
   "release",
@@ -90,6 +95,8 @@ const BOOLEAN_FLAGS = new Set([
   "fix",
   "next",
   "force",
+  "reopen",
+  "lock-only",
 ])
 
 /**
@@ -99,14 +106,26 @@ const BOOLEAN_FLAGS = new Set([
  */
 const REPEATABLE_FLAGS = new Set(["board"])
 
+/**
+ * Repeatable flags whose values are free text — collected verbatim into a
+ * list, never comma-joined, because an ask like "check A, then B" must
+ * survive as one ask.
+ */
+const MULTI_FLAGS = new Set(["ask"])
+
 function parseArgs(argv: string[]): Args {
   const positional: string[] = []
   const flags: Record<string, string | boolean> = {}
+  const multi: Record<string, string[]> = {}
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]
     if (arg.startsWith("--")) {
       const name = arg.slice(2)
       const set = (key: string, value: string): void => {
+        if (MULTI_FLAGS.has(key)) {
+          ;(multi[key] ??= []).push(value)
+          return
+        }
         const prior = flags[key]
         flags[key] =
           REPEATABLE_FLAGS.has(key) && typeof prior === "string" ? `${prior},${value}` : value
@@ -123,7 +142,7 @@ function parseArgs(argv: string[]): Args {
       positional.push(arg)
     }
   }
-  return { positional, flags }
+  return { positional, flags, multi }
 }
 
 function str(flags: Args["flags"], name: string): string | undefined {
@@ -142,19 +161,19 @@ function openStore(): Store {
   return openBoard(root)
 }
 
-/** The prefix a ref carries, if any: "TAS-12" → "TAS", "12" → null. */
+/** The prefix a ref carries, if any: "TAS-x7k4m" → "TAS", "x7k4m" → null. */
 function refPrefix(ref: string): string | null {
-  const match = /^([A-Za-z0-9]+)-\d+$/.exec(ref.trim())
+  const match = /^([A-Za-z0-9]+)-[A-Za-z0-9]+$/.exec(ref.trim())
   return match ? match[1].toUpperCase() : null
 }
 
 /**
- * The board a ref belongs to. A bare number means the nearest board, as ever —
+ * The board a ref belongs to. A bare key means the nearest board, as ever —
  * but a prefixed id is an address, and it routes: if the prefix isn't the
  * nearest board's, every board in the repo (walking up to the outermost board
- * root, then down) is searched for it, so `task show TAS-12` works from
+ * root, then down) is searched for it, so `task show TAS-x7k4m` works from
  * anywhere in a monorepo. What this must never do is what it used to: silently
- * strip a foreign prefix and act on the nearest board's ticket of that number.
+ * strip a foreign prefix and act on the nearest board's ticket of that key.
  */
 function openStoreFor(ref: string | undefined): Store {
   const prefix = ref ? refPrefix(ref) : null
@@ -192,7 +211,7 @@ function openStoreFor(ref: string | undefined): Store {
  * instead of reinterpreting it — this guards the second id in `task link`,
  * where the board was picked by the first.
  */
-function parseRefOn(store: Store, ref: string): number {
+function parseRefOn(store: Store, ref: string): string {
   const prefix = refPrefix(ref)
   if (prefix && prefix !== store.config.prefix.toUpperCase()) {
     fail(`${ref} is not on the ${store.config.prefix} board — links can't cross boards`)
@@ -238,8 +257,6 @@ function patchFromFlags(flags: Args["flags"]): TaskPatch {
   if (tags !== undefined) patch.tags = parseTags(tags)
   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")
@@ -304,16 +321,23 @@ 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] [--goal <slug>] [--needs-human]`)
+  if (!title) fail(`usage: task add <title> [--description …] [--status …] [--tags a,b] [--goal <slug>] [--ask "<text>"]…`)
   const store = openStore()
   const patch = patchFromFlags(args.flags)
   const pr = str(args.flags, "pr")
   if (pr) patch.prs = [...(patch.prs ?? []), pr]
-  const task = store.create({ title, ...patch })
+  let task = store.create({ title, ...patch })
+  const asks = (args.multi.ask ?? []).map((a) => a.trim()).filter(Boolean)
+  if (asks.length > 0) {
+    const author = resolveAuthor(str(args.flags, "author")).name
+    for (const text of asks) store.addAsk(task.key, text, author)
+    task = store.get(task.key)!
+  }
   if (args.flags.json) {
     console.log(JSON.stringify({ task }, null, 2))
   } else {
     printTask(task)
+    for (const ask of task.asks) console.log(`  ask [${ask.ordinal}] ${ask.text.split("\n")[0]}`)
   }
 }
 
@@ -500,7 +524,7 @@ function cmdArchive(args: Args): void {
 
   const store = openStore()
   const finished = store.list({ statuses: ["done", "canceled"] })
-  const archived = finished.map((t) => store.archive(t.number))
+  const archived = finished.map((t) => store.archive(t.key))
   if (args.flags.json) {
     console.log(JSON.stringify({ archived }, null, 2))
   } else if (archived.length === 0) {
@@ -526,10 +550,10 @@ function cmdShow(args: Args): void {
   const ref = args.positional[0]
   if (!ref) fail("usage: task show <id>")
   const store = openStoreFor(ref)
-  const number = store.parseId(ref)
-  const task = store.get(number)
-  if (!task) fail(`no such task: ${store.displayId(number)}`)
-  const comments = store.comments(number)
+  const key = store.parseId(ref)
+  const task = store.get(key)
+  if (!task) fail(`no such task: ${store.displayId(key)}`)
+  const comments = store.comments(key)
   // The goal rides along in full — title *and* description — so an agent
   // picking the ticket up cold inherits the shared context without it being
   // pasted into every ticket. null when unset or when the ref dangles.
@@ -539,17 +563,27 @@ function cmdShow(args: Args): void {
     return
   }
   // A linked task is only as useful as knowing whether it's still in the way.
-  const describeLinks = (numbers: number[]): string =>
-    numbers
-      .map((n) => {
-        const other = store.get(n)
-        return other ? `${other.id} (${other.status})` : store.displayId(n)
+  const describeLinks = (keys: string[]): string =>
+    keys
+      .map((k) => {
+        const other = store.get(k)
+        return other ? `${other.id} (${other.status})` : store.displayId(k)
       })
       .join(", ")
   console.log(`${task.id}  ${task.title}`)
   console.log(`status    ${task.status}`)
   if (task.archived) console.log(`archived  yes — \`task unarchive ${task.id}\` to edit`)
-  if (task.needsHuman) console.log(`needs     a human`)
+  const openAsks = task.asks.filter((a) => !a.resolvedAt)
+  if (openAsks.length) {
+    console.log(`needs     a human — ${openAsks.length} open ask${openAsks.length === 1 ? "" : "s"}`)
+  }
+  for (const ask of task.asks) {
+    const state = ask.resolvedAt
+      ? `✓ resolved${ask.resolvedBy ? ` by ${ask.resolvedBy}` : ""}`
+      : `○ open${ask.author ? ` · ${ask.author}` : ""} · ${ask.createdAt.slice(0, 10)}`
+    console.log(`ask [${ask.ordinal}]   ${ask.text.split("\n").join("\n          ")}`)
+    console.log(`          ${state}`)
+  }
   if (task.tags.length) console.log(`tags      ${task.tags.join(", ")}`)
   if (task.goal) {
     console.log(`goal      ${task.goal}${goal ? ` — ${goal.title}${goal.archived ? " (archived)" : ""}` : ""}`)
@@ -577,16 +611,16 @@ function cmdUpdate(args: Args): void {
   const ref = args.positional[0]
   if (!ref) fail("usage: task update <id> [--status …] [--title …] …")
   const store = openStoreFor(ref)
-  const number = store.parseId(ref)
+  const key = store.parseId(ref)
   const patch = patchFromFlags(args.flags)
   const pr = str(args.flags, "pr")
   if (pr) {
     // Append, dedup — `--pr <url>` is "attach this PR", not "replace the list".
-    const current = patch.prs ?? store.get(number)?.prs ?? []
+    const current = patch.prs ?? store.get(key)?.prs ?? []
     patch.prs = current.includes(pr) ? current : [...current, pr]
   }
   if (Object.keys(patch).length === 0) fail("nothing to update — pass at least one flag")
-  const task = store.update(number, patch)
+  const task = store.update(key, patch)
   if (args.flags.json) {
     console.log(JSON.stringify({ task }, null, 2))
   } else {
@@ -597,7 +631,7 @@ function cmdUpdate(args: Args): void {
 function cmdMove(args: Args): void {
   const [ref, status] = args.positional
   if (!ref || !status) fail("usage: task move <id> <status>")
-  cmdUpdate({ positional: [ref], flags: { ...args.flags, status } })
+  cmdUpdate({ positional: [ref], flags: { ...args.flags, status }, multi: {} })
 }
 
 /**
@@ -628,6 +662,129 @@ function cmdPromote(args: Args): void {
   }
 }
 
+/**
+ * `task ask <id> <text>` — file one thing a person owes this ticket. The ask
+ * is the primitive every human requirement funnels through: it derives the
+ * needs-human badge, feeds `task inbox`, and gates `done` until resolved.
+ * On a claimed ticket the write lands on the claim branch as a pushed commit
+ * (see claim-io.ts) — the worker's done gate has to see debt filed mid-claim.
+ */
+function cmdAsk(args: Args): void {
+  const [ref, ...rest] = args.positional
+  const text = rest.join(" ").trim()
+  if (!ref || !text) fail(`usage: task ask <id> "<what a person needs to do>" [--author <who>]`)
+  const store = openStoreFor(ref)
+  const author = resolveAuthor(str(args.flags, "author")).name
+  const { ask, branch } = addAskRouted(store, store.parseId(ref), text, author)
+  if (args.flags.json) {
+    console.log(JSON.stringify({ ask, branch }, null, 2))
+  } else {
+    console.log(`asked on ${ask.taskId} [${ask.ordinal}]  ${ask.text.split("\n")[0]}`)
+    if (branch) console.log(`committed and pushed to ${branch} — the claim owns this ticket's asks`)
+  }
+}
+
+/**
+ * `task resolve <id> <n>` — check an ask off (`--reopen` puts it back). The
+ * ordinal is the one `task show` prints; the optional --comment lands as an
+ * attributed comment so the answer travels with the ticket, not just the
+ * checkbox. Resolving the last open ask is the moment a ticket usually moves
+ * to done — the hint below says so rather than doing it, because finishing a
+ * ticket is a statement about the *work*, not the asks.
+ */
+function cmdResolve(args: Args): void {
+  const [ref, askRef] = args.positional
+  if (!ref || !askRef) {
+    fail('usage: task resolve <id> <ordinal> [--comment "<note>"] [--reopen] [--author <who>]')
+  }
+  const store = openStoreFor(ref)
+  const key = store.parseId(ref)
+  const author = resolveAuthor(str(args.flags, "author")).name
+  const { ask, branch } = setAskResolvedRouted(
+    store,
+    key,
+    askRef,
+    !args.flags.reopen,
+    author,
+  )
+  const note = str(args.flags, "comment")?.trim()
+  const comment = note
+    ? store.addComment(
+        key,
+        `${args.flags.reopen ? "Reopened" : "Resolved"} ask [${ask.ordinal}] (${ask.text.split("\n")[0]}): ${note}`,
+        author,
+      )
+    : null
+  const task = store.get(key)!
+  // Branch-resolved asks aren't in the local files — count what's still open
+  // on the side that was just written.
+  const remaining = branch
+    ? undefined
+    : task.asks.filter((a) => !a.resolvedAt).length
+  if (args.flags.json) {
+    console.log(JSON.stringify({ ask, branch, comment, openAsks: remaining ?? null }, null, 2))
+    return
+  }
+  const verb = args.flags.reopen ? "reopened" : "resolved"
+  console.log(`${verb} ${ask.taskId} [${ask.ordinal}]  ${ask.text.split("\n")[0]}`)
+  if (branch) {
+    console.log(`committed and pushed to ${branch} — the worker sees it on its next pull`)
+    return
+  }
+  if (args.flags.reopen) return
+  if (remaining !== undefined && remaining > 0) {
+    console.log(`${remaining} ask${remaining === 1 ? "" : "s"} still open on ${ask.taskId}`)
+  } else if (task.status === "in_progress") {
+    console.log(`that was the last open ask — \`task move ${ask.taskId} done\` if the work is finished too`)
+  }
+}
+
+/**
+ * `task inbox` — what do I need to do NOW to unblock work: every open ask on
+ * effectively-in-progress tickets (file status, or a live claim branch —
+ * see inbox.ts), across the repo's boards, oldest owed first. Deliberately
+ * cross-board, like `claim --next`: the queue's attention is per-board, a
+ * person's isn't.
+ */
+function cmdInbox(args: Args): void {
+  let entries: InboxEntry[]
+  try {
+    const scope = findScopeRoot(process.cwd())
+    const boards = selectionBoards(process.cwd(), boardFlag(args)).map((store) => {
+      const rel = relative(scope, store.root).split(sep).join("/")
+      return { id: rel === "" ? "." : rel, store }
+    })
+    entries = buildInbox(boards)
+  } catch (error) {
+    if (error instanceof ClaimError) fail(error.message)
+    throw error
+  }
+  if (args.flags.json) {
+    console.log(JSON.stringify({ inbox: entries }, null, 2))
+    return
+  }
+  if (entries.length === 0) {
+    console.log("inbox zero — no open asks on in-progress work")
+    return
+  }
+  const open = entries.reduce((sum, e) => sum + e.asks.length, 0)
+  console.log(
+    `${open} open ask${open === 1 ? "" : "s"} across ${entries.length} ticket${entries.length === 1 ? "" : "s"}`,
+  )
+  const age = (iso: string): string => {
+    const days = Math.floor((Date.now() - Date.parse(iso)) / 86_400_000)
+    return days > 0 ? `${days}d` : "today"
+  }
+  for (const entry of entries) {
+    const via = entry.claim ? `  (claimed: ${entry.claim.branch})` : ""
+    console.log(`\n${entry.task.id}  ${entry.task.title}${via}`)
+    for (const ask of entry.asks) {
+      const who = ask.author ? ` · ${ask.author}` : ""
+      console.log(`  [${ask.ordinal}] ${ask.text.split("\n")[0]}  (${age(ask.createdAt)}${who})`)
+    }
+  }
+}
+
 function cmdComment(args: Args): void {
   const [ref, ...rest] = args.positional
   const body = rest.join(" ").trim()
@@ -657,9 +814,9 @@ function cmdLink(args: Args, action: "link" | "unlink"): void {
   const store = openStoreFor(ref)
   const relation = blocks ? "blocks" : "blocked_by"
   const target = parseRefOn(store, (blocks ?? blockedBy)!)
-  const number = store.parseId(ref)
+  const key = store.parseId(ref)
   const task =
-    action === "link" ? store.link(number, relation, target) : store.unlink(number, relation, target)
+    action === "link" ? store.link(key, relation, target) : store.unlink(key, relation, target)
   if (args.flags.json) {
     console.log(JSON.stringify({ task }, null, 2))
   } else {
@@ -673,7 +830,7 @@ function cmdLink(args: Args, action: "link" | "unlink"): void {
 }
 
 const CLAIM_USAGE =
-  'usage: task claim <id> | task claim --next | task claim --release <id> --comment "<why>"'
+  '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
@@ -684,11 +841,21 @@ const CLAIM_USAGE =
 function cmdClaim(args: Args): void {
   const ref = args.positional[0]
   const options = { force: Boolean(args.flags.force) }
-  const printClaim = (result: { task: Task; branch: string; base: string }): void => {
+  const printClaim = (result: { task: Task; branch: string; base: string; previous: 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`)
+      // 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 {
@@ -697,7 +864,7 @@ function cmdClaim(args: Args): void {
       // 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)
+      if (args.flags.release || args.flags["lock-only"]) fail(CLAIM_USAGE)
       const result = claimNext(selectionBoards(process.cwd(), boardFlag(args)), options)
       if (!result) {
         if (args.flags.json) {
@@ -712,7 +879,31 @@ function cmdClaim(args: Args): void {
     }
     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
@@ -723,26 +914,26 @@ function cmdClaim(args: Args): void {
           '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) {
       console.error(`error: ${error.message}`)
@@ -752,6 +943,50 @@ function cmdClaim(args: Args): void {
   }
 }
 
+/**
+ * `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: Args): void {
+  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(): void {
   // skill/ ships in the npm package; `../` from both dist/cli.js and
@@ -774,7 +1009,10 @@ function cmdOverview(args: Args): void {
     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(
@@ -967,9 +1205,9 @@ function cmdDelete(args: Args): void {
   const ref = args.positional[0]
   if (!ref) fail("usage: task delete <id>")
   const store = openStoreFor(ref)
-  const number = store.parseId(ref)
-  store.delete(number)
-  console.log(`deleted ${store.displayId(number)}`)
+  const key = store.parseId(ref)
+  store.delete(key)
+  console.log(`deleted ${store.displayId(key)}`)
 }
 
 /**
@@ -1165,11 +1403,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>]
@@ -1183,18 +1424,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>
@@ -1202,7 +1463,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
@@ -1215,8 +1476,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
@@ -1232,18 +1506,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>
@@ -1265,7 +1557,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
@@ -1297,15 +1589,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
@@ -1354,8 +1649,16 @@ function main(): void | Promise<void> {
       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":