@nickmeriano/task 0.7.1 → 0.9.0

package/skill/SKILL.md

@@ -34,21 +34,47 @@ for parsing.
 ## Commands
 
 ```bash
-task list [--status s1,s2] [--tag a,b] [--milestone m] [--needs-human] [--all] --json
-task show <id> --json                  # full task + comments
-task add "Title" [--description text] [--status s] [--tags a,b]
-                 [--milestone m] [--needs-human] --json
-task update <id> [--title t] [--description text] [--status s] [--tags a,b]
-                 [--milestone m] [--needs-human | --no-needs-human] --json
-task start <id>                        # → in_progress
-task done <id>                         # → done
-task move <id> <status>                # any status change
+task list [--status s1,s2] [--tag a,b] [--goal g] [--needs-human] [--all] --json
+task show <id> --json                  # full task + comments + its goal's
+                                       # title and description, inlined
+task search <query> [--archived] --json  # match titles, descriptions, comments;
+                                       # --archived searches the archive too
+task add "Title" [--description text | --description-file path|-] [--status s]
+                 [--tags a,b] [--goal g] [--ask "text"]… --json
+                                       # long markdown descriptions: write a
+                                       # file (or pipe stdin with -) instead
+                                       # of fighting shell quoting — never
+                                       # hand-edit ticket files
+task update <id> [--title t] [--description text | --description-file path|-]
+                 [--status s] [--tags a,b] [--goal g] --json
+task move <id> <status>                # the one status API — every plain
+                                       # status change goes through it;
+                                       # done is refused while asks are open
+task ask <id> "what a person owes" --author claude --json
+                                       # file an ask — see "Asks" below
+task resolve <id> <n> [--comment "note"] [--reopen] --json
+                                       # check ask <n> off (show prints the
+                                       # ordinals); the note lands as a comment
+task inbox [--board P] --json          # every open ask on effectively
+                                       # in-progress tickets, repo-wide —
+                                       # the human's "what do I owe" queue
+task promote <id> --json               # backlog → todo — the human "build
+                                       # this" call; see "Promotion" below
 task link <id> --blocked-by <id>       # mark a dependency (or --blocks)
 task unlink <id> --blocked-by <id>     # remove one (or --blocks)
 task update <id> --pr <url>            # attach a pull request (appends)
+task goal add "Title" [--slug s] [--description text] --json
+task goal list [--archived] --json     # every goal + derived done/total counts
+task goal show <slug> --json           # the goal, its description, its tasks
+task goal update <slug> [--title t] [--description text] --json
+task goal archive <slug>               # refused while it has open tasks
+task goal delete <slug>                # refused while any live task references it
 task claim <id>                        # claim a ticket before working it
-task claim --release <id>              # abandon a claim cleanly
+task claim --next --json               # claim the top claimable ticket in one call
+task claim --release <id> --comment "why"  # abandon a claim, reason required
 task list --claimable --json           # the claim queue, top entry = next up
+task overview --json                   # one screen of board health
+task instructions                      # print these conventions (this file)
 task comment <id> "text" --author claude
 task delete <id>
 task boards --json                     # every board in the repo, with prefixes
@@ -56,6 +82,8 @@ task archive <id> --json               # done/canceled ticket -> .task/archive/
 task archive --all --json              # archive everything done or canceled
 task unarchive <id> --json             # put one back on the board
 task whoami                            # who comments are attributed to
+task check [--fix] --json              # lint the board files (dangling refs,
+                                       # bad files); --fix repairs mechanically
 ```
 
 `task publish` and `task unpublish` also exist — they give the board a URL so
@@ -63,12 +91,22 @@ the user can read it from a phone, and take it away again. Both open a browser
 and wait for a human, so **never run either on your own initiative**; suggest
 `task publish` if the user wants to see the board remotely.
 
-- `<id>` is `PREFIX-12` or just `12`. A bare number means the nearest board;
+- `<id>` is `PREFIX-x7k4m`, a bare `x7k4m`, or any unique prefix of a key
+  (`task show x7` resolves git-style; an ambiguous prefix errors naming the
+  matches). Ids are random 5-character keys minted branch-safely at `task
+  add` — never sequential. A bare key means the nearest board;
   a prefixed id routes to whichever board in the repo owns that prefix, so
-  `TAS-12` works from any directory. `task boards --json` lists them all.
+  `TAS-x7k4m` works from any directory. `task boards --json` lists them all.
 - Statuses: `backlog` `todo` `in_progress` `done` `canceled`.
 - `--tag a,b` matches a task carrying *either* tag, not both.
-- Clear a field by passing it empty: `--tags ""`, `--milestone ""`, `--prs ""`.
+- Clear a field by passing it empty: `--tags ""`, `--goal ""`, `--prs ""`.
+- Long markdown goes through **stdin**, not shell quoting and never a
+  hand-edited ticket file — `task update NIC-x7k4m --description-file - <<'EOF'
+  … EOF`. This path is byte-faithful: what you pipe is exactly what's stored
+  (the web UI's rich-text editor, by contrast, re-serializes markdown on
+  save). To append (e.g. a plan), read the current text from `--json` first
+  and pipe back original + addition — the flag replaces the whole
+  description.
 - `task list` hides done/canceled by default; `--all` shows everything, and
   `--archived` lists the archive instead of the board.
 - Archiving is history, not deletion: only done/canceled tickets qualify,
@@ -85,34 +123,87 @@ ordering ("this can't land until X does"), record it with `task link` instead
 of prose in a comment. Blocked tasks wear a red "Blocked" badge on the board
 until every blocker is done or canceled.
 
+**Asks.** An ask is one thing a *person* owes a ticket — a credential only
+they can mint, a decision that isn't yours, an action against production.
+File it the moment you hit it: `task ask <id> "Mint the OAuth app and put the
+client id in repo secrets" --author claude`. Asks are the primitive every
+human requirement funnels through: the amber needs-human badge is derived
+from them, `task inbox` aggregates the open ones, and `task move <id> done`
+is **refused while any ask is open** — done means nobody owes anything.
+They deliberately do *not* block claiming or your own work: implement
+everything that doesn't depend on the ask and let the person's part run in
+parallel. If the work truly can't *start* before the ask (a design decision
+the whole ticket hangs on), that's not an ask — put the decision on its own
+ticket and `task link <id> --blocked-by` it. An ask that outlives its ticket
+is a new ticket, not a lingering ask. Humans resolve asks (`task resolve`),
+usually from the board UI; resolve one yourself only when the person has
+told you it's done — attribution keeps that honest. On a **claimed** ticket
+the branch owns the asks: ask writes from any other checkout land on the
+claim branch as pushed commits (the CLI says so when it happens), so pull
+your claim branch before reading it — resolutions arrive from outside.
+When some other workflow of yours needs the owner's attention, prefer
+filing an ask over inventing a new channel: the inbox is the one place
+they look.
+
+**Promotion.** `backlog` → `todo` is the human "build this" decision, and
+`task promote <id>` is its verb. There is no quality gate — a one-line
+backlog ticket promotes, because planning happens at claim time, not before.
+Blocked tickets still promote (the hold is reported, in `holds` with
+`--json`): blockers are claim-time gates that `claim` and `--claimable`
+enforce live, so promoting a blocked ticket just queues it behind its
+blockers. Prefer `promote` over `update --status todo` / `move` for this
+transition — it refuses non-backlog sources and reports holds. **Never
+promote on your own initiative**; a person promotes.
+
 **Claiming.** On a board worked by several sessions (scheduled agents, other
 humans), `task claim <id>` is the lock that keeps two workers off the same
-ticket: it branches `<claimPrefix><prefix>-<n>` off origin's default branch
-(`claimPrefix` in `.task/config.json`, default `task/claim/`), flips the
-ticket to `in_progress` as the branch's first commit, and pushes. The branch
-existing on origin *is* the claim — atomic, because the push only succeeds if
-the branch doesn't exist yet. Exit codes: `0` claimed (you're on the branch,
-start working), `1` already claimed (pick another ticket), `2` not claimable
-(not todo, blocked, needs-human, or dirty tree). **Claim before you work**:
-if you're about to implement a `todo` ticket in a repo that claims (a
-`claimPrefix` in the config, or claims visible in
-`git ls-remote origin '<claimPrefix>*'`), run `task claim <id>` first so no
+ticket: it branches `<branchPrefix><prefix>-<key>` off origin's default branch
+(`claims.branchPrefix` in `.task/config.json`, default `task/claim/`), flips
+the ticket to `in_progress` as the branch's first commit, and pushes. The
+branch existing on origin *is* the claim — atomic, because the push only
+succeeds if the branch doesn't exist yet. Exit codes: `0` claimed (you're on
+the branch, start working), `1` already claimed (pick another ticket), `2`
+not claimable (not todo, blocked, dirty tree, or at the claim cap). Open
+asks don't gate a claim — a ticket can be yours to implement while a person
+owes it something. **Claim before you work**: if you're about to implement a `todo` ticket
+in a repo that claims (a `claims` block in the config, or claims visible in
+`git ls-remote origin '<branchPrefix>*'`), run `task claim <id>` first so no
 scheduled run picks it up under you — and do the whole ticket on the claim
-branch, `task done` + `--pr` included, so the merge lands code and status
-together. `task claim --release <id>` abandons a claim (deletes the branch
-both sides); `task list --claimable --json` is the queue. Never edit
-`claimPrefix` on your own initiative — it's the shared lock convention, and
-changing it strands every in-flight claim.
+branch, `task move <id> done` + `--pr` included, so the merge lands code and status
+together. Never edit `claims.branchPrefix` on your own initiative — it's the
+shared lock convention, and changing it strands every in-flight claim.
+
+`task claim --next --json` claims the top claimable ticket in one call and is
+the first move of a scheduled worker: it walks the selection scope in
+priority order, retries past lost races internally, and exits `0` claimed
+(printing the ticket), `1` queue empty (stop cleanly — no work), `2`
+preconditions failed. The scope comes from the root board's top-level
+`"boards"` list in `.task/config.json` (board prefixes, list order =
+priority; absent → the nearest board only); `--board TAS` (repeatable)
+overrides it. The list is selection scope, not permission — an explicit
+`task claim <id>` works on any board. `task list --claimable --json` is the
+same queue without the claim.
+
+The root board's `claims.maxOpenCount` is a repo-wide WIP cap: while that
+many claim branches exist on origin, every new claim is refused (exit `2`).
+Don't reach for `--force` on your own initiative — the cap usually means
+merge or release something first.
+
+**Releasing.** `task claim --release <id> --comment "why"` abandons a claim:
+it deletes the branch on both sides, then records the required comment on the
+ticket (attributed like `task comment`, left uncommitted in your working
+tree) so the next worker inherits what was tried instead of rediscovering it.
+Say what you attempted and where it went wrong, not just "releasing".
 
 **Pull requests.** When you open a PR for a task, attach it:
 `task update <id> --pr <url>`. Put the task id in the PR title too (e.g.
-`[TAS-6] Fix retry loop`) so the two reference each other from both sides.
+`[TAS-x7k4m] Fix retry loop`) so the two reference each other from both sides.
 `--pr` appends one URL; `--prs url1,url2` replaces the whole list.
 
 ## How to work with the board
 
 **Starting work.** Before picking up a request, check `task list --json` —
-the work may already be tracked. If it is, `task start <id>` so the board
+the work may already be tracked. If it is, `task move <id> in_progress` so the board
 shows it moving. If it isn't and the work is more than a quick edit, create a
 task first: the user watching the board should be able to tell what you're
 doing without reading your transcript.
@@ -124,18 +215,19 @@ new work you're not going to do now (a bug, a refactor, a follow-up), don't
 let it evaporate: `task add` it to `backlog` or `todo` with enough description
 that someone else could pick it up cold.
 
-**Finishing.** `task done <id>` only when the work is actually done — code
+**Finishing.** `task move <id> done` only when the work is actually done — code
 written, checks passing. If you're stopping partway, leave it `in_progress`
 with a comment saying exactly where you stopped and what's left. If the work
 turned out to be unnecessary, `task move <id> canceled` with a comment saying
 why — a canceled task with a reason beats a deleted one.
 
-**When you can't finish it alone.** Some tickets need a person: a credential
-only they can issue, a design call that isn't yours to make, an action against
-production. Mark those `--needs-human`, comment saying exactly what you need,
-and leave the task `in_progress` — not `done`. Moving it to `done` because
-your part is finished hides the one thing the board exists to surface. Clear
-the flag with `--no-needs-human` once the person has unblocked it.
+**When you can't finish it alone.** File an ask — `task ask <id> "exactly
+what you need" --author claude` — then keep going on everything that doesn't
+depend on it, and leave the ticket `in_progress` when your part runs out.
+Don't fight the done gate: a refused `task move <id> done` is the board
+telling you a person still owes something, and that surfacing is the whole
+point. There is no needs-human flag to set — the badge derives from open
+asks, so saying what's owed is the only way to raise it.
 
 **Attribution.** Pass `--author claude` on your comments so the user can tell
 your updates from theirs. Their own comments are attributed automatically from
@@ -149,9 +241,18 @@ webhook", not "webhook bug". Descriptions carry the context you'd want if you
 picked the task up cold: the file paths involved, the constraint that makes it
 non-obvious, the definition of done. Tags are lowercase single words
 (`api`, `infra`, `ui`, `bug`) — reuse the repo's existing tags
-(`task list --all --json` shows what's in use) before inventing new ones. A
-milestone is the one release or push a task belongs to; there's at most one,
-and the same rule applies — join an existing one rather than coining a variant.
+(`task list --all --json` shows what's in use) before inventing new ones.
+
+**Goals.** A goal is a titled, described destination (`task goal add`); a task
+belongs to **at most one**. The split to keep straight: the goal answers
+"where is this going" (one), tags answer "what kind" (many) — something that
+wants to live in two goals is a tag. The goal's description carries the
+strategic why that its tickets share; keep each ticket self-sufficient for the
+how, and put the shared context in the goal instead of pasting it into every
+ticket (`task show` inlines it automatically). Goals have no status — progress
+is derived from their tasks — and `task goal archive` shelves a finished one
+once nothing open references it. Don't mint goals casually: if it doesn't
+deserve a description, it's a tag.
 
 ## The UI
 
@@ -167,3 +268,15 @@ package's `.task/`) from one server — the header becomes a board switcher.
 This changes nothing for the other commands: they still operate on the
 nearest `.task/` walking up from the current directory, so `cd` into the
 package whose board you mean before running them.
+
+On a git checkout with an origin, the served UI also carries a git surface:
+a branch chip (current branch, dirty board files, ahead/behind), board-scoped
+commits (`chore(board): …`, pathspec-limited to `.task/` so unrelated dirty
+code never rides along), a branch switcher that does a real checkout, and PR
+affordances. Two consequences for you: board edits made through the UI are
+working-tree writes the user can now see and commit themselves — so don't
+commit board files for them unprompted; and dragging a claimed ticket out of
+In Progress in the UI performs a real `task claim --release` (the claim
+branch and its commits are deleted) after an explicit confirm — if your claim
+disappears mid-run, check the ticket's comments for the release note before
+assuming a race.

package/src/asks.test.ts

@@ -0,0 +1,355 @@
+/**
+ * Asks (TAS-38): the checklist a person owes a ticket, and everything derived
+ * from it.
+ *
+ * 1. An ask is one file under tickets/<key>/asks/, comment-shaped; `needsHuman`
+ *    is derived from open asks, never stored.
+ * 2. Done is gated: open asks refuse the move, resolving clears it, canceled
+ *    voids without ceremony. A finished ticket can't start owing again —
+ *    addAsk/reopen are refused on done/canceled.
+ * 3. Ordinals are creation-order positions — stable across resolution, the
+ *    handle `task resolve <id> <n>` takes.
+ * 4. `task inbox` answers "what do I owe NOW": open asks on effectively
+ *    in-progress tickets — file status, or a live claim branch, whose ask
+ *    files are read from the branch itself.
+ */
+
+import assert from "node:assert/strict"
+import { test } from "node:test"
+import { execFile, execFileSync } from "node:child_process"
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { initProject } from "./file-store.ts"
+import type { Ask, Task } from "./types.ts"
+import type { InboxEntry } from "./inbox.ts"
+
+const CLI = fileURLToPath(new URL("./cli.ts", import.meta.url))
+
+function tempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "task-asks-test-"))
+  process.on("exit", () => rmSync(dir, { recursive: true, force: true }))
+  return dir
+}
+
+interface CliResult {
+  code: number
+  stdout: string
+  stderr: string
+}
+
+function cli(cwd: string, ...args: string[]): Promise<CliResult> {
+  return new Promise((resolve) => {
+    execFile(
+      process.execPath,
+      ["--experimental-strip-types", CLI, ...args],
+      { cwd },
+      (error, stdout, stderr) => {
+        resolve({ code: error ? ((error as { code?: number }).code ?? 1) : 0, stdout, stderr })
+      },
+    )
+  })
+}
+
+// ── The store-level contract ─────────────────────────────────────────────────
+
+test("an ask is a file; needsHuman derives from it and resolution round-trips", () => {
+  const dir = tempDir()
+  const store = initProject(dir, { name: "ask board", prefix: "ASK" })
+  const task = store.create({ title: "Wire the webhook", status: "in_progress" })
+  assert.equal(store.get(task.key)!.needsHuman, false)
+
+  const ask = store.addAsk(task.key, "Mint the API token and add it to secrets", "claude")
+  assert.equal(ask.ordinal, 1)
+  assert.equal(ask.resolvedAt, null)
+
+  // One file, comment-shaped, under asks/ — mergeable by construction.
+  const dirPath = join(dir, ".task", "tickets", task.key, "asks")
+  const files = readdirSync(dirPath)
+  assert.equal(files.length, 1)
+  const text = readFileSync(join(dirPath, files[0]), "utf8")
+  assert.match(text, /^---\nauthor: "claude"\ncreated: /)
+  assert.match(text, /Mint the API token/)
+
+  const withAsk = store.get(task.key)!
+  assert.equal(withAsk.needsHuman, true)
+  assert.equal(withAsk.asks.length, 1)
+
+  const resolved = store.resolveAsk(task.key, "1", "nick")
+  assert.equal(resolved.resolvedBy, "nick")
+  assert.notEqual(resolved.resolvedAt, null)
+  assert.equal(store.get(task.key)!.needsHuman, false)
+  assert.match(readFileSync(join(dirPath, files[0]), "utf8"), /resolved_by: "nick"/)
+
+  const reopened = store.reopenAsk(task.key, resolved.id)
+  assert.equal(reopened.resolvedAt, null)
+  assert.equal(store.get(task.key)!.needsHuman, true)
+  store.close()
+})
+
+test("ordinals are creation order and stay put as asks resolve", () => {
+  const dir = tempDir()
+  const store = initProject(dir, { name: "ask board", prefix: "ASK" })
+  const task = store.create({ title: "Ship it", status: "in_progress" })
+  store.addAsk(task.key, "First owed thing", "claude")
+  store.addAsk(task.key, "Second owed thing", "claude")
+  store.resolveAsk(task.key, "1", "nick")
+
+  const asks = store.asks(task.key)
+  assert.deepEqual(asks.map((a) => a.ordinal), [1, 2])
+  assert.equal(asks[0].resolvedAt !== null, true)
+  assert.equal(asks[1].text, "Second owed thing")
+
+  // The needs-human filter matches the derived flag.
+  assert.deepEqual(store.list({ needsHuman: true }).map((t) => t.key), [task.key])
+  store.close()
+})
+
+test("done is gated on zero open asks; canceled voids them", () => {
+  const dir = tempDir()
+  const store = initProject(dir, { name: "ask board", prefix: "ASK" })
+  const task = store.create({ title: "Gated", status: "in_progress" })
+  store.addAsk(task.key, "Approve the cutover window", "claude")
+
+  assert.throws(
+    () => store.update(task.key, { status: "done" }),
+    /1 open ask.*done means nobody owes anything/s,
+  )
+
+  // Canceling is allowed with the asks still open — a dead ticket's asks die
+  // with it — and once canceled, no new debt can accrue.
+  store.update(task.key, { status: "canceled" })
+  assert.throws(() => store.addAsk(task.key, "Too late", "claude"), /is canceled/)
+  store.update(task.key, { status: "in_progress" })
+
+  store.resolveAsk(task.key, "1", "nick")
+  const done = store.update(task.key, { status: "done" })
+  assert.equal(done.status, "done")
+
+  // A finished ticket can't quietly start owing things again.
+  assert.throws(() => store.addAsk(task.key, "One more thing", "claude"), /is done/)
+  assert.throws(() => store.reopenAsk(task.key, "1"), /reopening an ask/)
+  store.close()
+})
+
+// ── The CLI surface ──────────────────────────────────────────────────────────
+
+test("task ask / resolve / show: the full loop, exit codes and ordinals", async () => {
+  const dir = tempDir()
+  initProject(dir, { name: "cli board", prefix: "CLI" }).close()
+  const created = await cli(dir, "add", "Needs a person", "--status", "in_progress", "--json")
+  const id = (JSON.parse(created.stdout) as { task: Task }).task.id
+
+  const asked = await cli(dir, "ask", id, "Run setup.sh once the token exists", "--author", "claude")
+  assert.equal(asked.code, 0, asked.stderr)
+  assert.ok(asked.stdout.includes(`asked on ${id} [1]`), asked.stdout)
+
+  const shown = await cli(dir, "show", id, "--json")
+  const { task } = JSON.parse(shown.stdout) as { task: Task }
+  assert.equal(task.needsHuman, true)
+  assert.equal(task.asks[0].author, "claude")
+
+  // Done refuses while the ask is open — the gate speaks CLI too.
+  const blocked = await cli(dir, "move", id, "done")
+  assert.equal(blocked.code, 1)
+  assert.match(blocked.stderr, /open ask/)
+
+  const resolved = await cli(dir, "resolve", id, "1", "--comment", "done, it's in 1Password", "--author", "nick")
+  assert.equal(resolved.code, 0, resolved.stderr)
+  assert.ok(resolved.stdout.includes(`resolved ${id} [1]`), resolved.stdout)
+  assert.match(resolved.stdout, /last open ask/)
+
+  // The note landed as an attributed comment naming the ask.
+  const detail = await cli(dir, "show", id, "--json")
+  const { comments } = JSON.parse(detail.stdout) as { comments: { author: string; body: string }[] }
+  assert.equal(comments.length, 1)
+  assert.equal(comments[0].author, "nick")
+  assert.match(comments[0].body, /Resolved ask \[1\].*1Password/)
+
+  assert.equal((await cli(dir, "move", id, "done")).code, 0)
+  assert.equal((await cli(dir, "resolve", id, "9")).code, 1)
+})
+
+test("task add --ask files asks at creation, commas and all", async () => {
+  const dir = tempDir()
+  initProject(dir, { name: "cli board", prefix: "CLI" }).close()
+  const added = await cli(
+    dir, "add", "Born owing", "--status", "todo",
+    "--ask", "Approve the plan, then the budget",
+    "--ask", "Add STRIPE_SECRET_KEY to the worker",
+    "--json",
+  )
+  assert.equal(added.code, 0, added.stderr)
+  const { task } = JSON.parse(added.stdout) as { task: Task }
+  // One ask per --ask, verbatim — a comma never splits an ask in two.
+  assert.deepEqual(
+    task.asks.map((a: Ask) => a.text),
+    ["Approve the plan, then the budget", "Add STRIPE_SECRET_KEY to the worker"],
+  )
+  assert.equal(task.needsHuman, true)
+})
+
+test("inbox is in-progress only: todo asks wait for their claim", async () => {
+  const dir = tempDir()
+  const store = initProject(dir, { name: "inbox board", prefix: "INB" })
+  const active = store.create({ title: "Being worked", status: "in_progress" })
+  const queued = store.create({ title: "Waiting its turn", status: "todo" })
+  store.addAsk(active.key, "Upgrade the org to Pro", "claude")
+  store.addAsk(queued.key, "Decide pricing", "claude")
+  store.close()
+
+  // Not a git repo — the resolver degrades silently to file truth.
+  const result = await cli(dir, "inbox", "--json")
+  assert.equal(result.code, 0, result.stderr)
+  const { inbox } = JSON.parse(result.stdout) as { inbox: InboxEntry[] }
+  assert.deepEqual(inbox.map((e) => e.task.key), [active.key])
+  assert.equal(inbox[0].claim, null)
+  assert.equal(inbox[0].asks[0].text, "Upgrade the org to Pro")
+})
+
+// ── The claim-branch read (TAS-26's core) ────────────────────────────────────
+
+function sh(cwd: string, ...args: string[]): string {
+  return execFileSync(args[0], args.slice(1), { cwd, encoding: "utf8" }).trim()
+}
+
+test("a claimed ticket's asks reach the inbox from its branch", async () => {
+  const home = tempDir()
+  const bare = join(home, "origin.git")
+  sh(home, "git", "init", "--quiet", "--bare", "-b", "main", bare)
+
+  const seed = join(home, "seed")
+  sh(home, "git", "clone", "--quiet", bare, seed)
+  sh(seed, "git", "config", "user.name", "Test")
+  sh(seed, "git", "config", "user.email", "test@example.com")
+  const store = initProject(seed, { name: "claim inbox", prefix: "CIN" })
+  const key = store.create({ title: "Agent work with a human side", status: "todo" }).key
+  const branch = `task/claim/cin-${key}`
+  store.close()
+  sh(seed, "git", "add", "-A")
+  sh(seed, "git", "commit", "--quiet", "-m", "board")
+  sh(seed, "git", "push", "--quiet", "-u", "origin", "main")
+
+  // Worker: claim (flips the ticket on the branch), file an ask mid-run, push.
+  const worker = join(home, "worker")
+  sh(home, "git", "clone", "--quiet", bare, worker)
+  sh(worker, "git", "config", "user.name", "Worker")
+  sh(worker, "git", "config", "user.email", "worker@example.com")
+  assert.equal((await cli(worker, "claim", key)).code, 0)
+  assert.equal((await cli(worker, "ask", `CIN-${key}`, "Create the OAuth app in the dashboard", "--author", "claude")).code, 0)
+  sh(worker, "git", "add", "-A")
+  sh(worker, "git", "commit", "--quiet", "-m", "ask")
+  sh(worker, "git", "push", "--quiet", "origin", branch)
+
+  // Owner, on a fresh clone of main, where the ticket still reads `todo` and
+  // has no ask files at all: the inbox says what the claim branch knows.
+  const owner = join(home, "owner")
+  sh(home, "git", "clone", "--quiet", bare, owner)
+  sh(owner, "git", "config", "user.name", "Nick")
+  sh(owner, "git", "config", "user.email", "nick@example.com")
+  assert.equal(existsSync(join(owner, ".task", "tickets", key, "asks")), false)
+  const result = await cli(owner, "inbox", "--json")
+  assert.equal(result.code, 0, result.stderr)
+  const { inbox } = JSON.parse(result.stdout) as { inbox: InboxEntry[] }
+  assert.equal(inbox.length, 1)
+  assert.equal(inbox[0].task.status, "todo") // file truth, kept honest
+  assert.equal(inbox[0].claim?.branch, branch)
+  assert.deepEqual(inbox[0].asks.map((a) => a.text), ["Create the OAuth app in the dashboard"])
+
+  // The claim owns the ticket's asks, so the owner's writes land on the
+  // branch as pushed commits — the checkout never switches, the working
+  // tree never grows an ask file.
+  const resolved = await cli(owner, "resolve", `CIN-${key}`, "1", "--author", "nick")
+  assert.equal(resolved.code, 0, resolved.stderr)
+  assert.ok(resolved.stdout.includes(`committed and pushed to ${branch}`), resolved.stdout)
+  assert.equal(existsSync(join(owner, ".task", "tickets", key, "asks")), false)
+  assert.equal(sh(owner, "git", "rev-parse", "--abbrev-ref", "HEAD"), "main")
+
+  // A third clone reads the resolution straight off origin's branch.
+  const verify = join(home, "verify")
+  sh(home, "git", "clone", "--quiet", bare, verify)
+  sh(verify, "git", "fetch", "--quiet", "origin", branch)
+  const askFile = sh(verify, "git", "ls-tree", "--name-only", `FETCH_HEAD:.task/tickets/${key}/asks`)
+  assert.match(
+    sh(verify, "git", "show", `FETCH_HEAD:.task/tickets/${key}/asks/${askFile}`),
+    /resolved_by: "nick"/,
+  )
+  const cleared = await cli(owner, "inbox", "--json")
+  assert.equal((JSON.parse(cleared.stdout) as { inbox: InboxEntry[] }).inbox.length, 0)
+
+  // Adding to a claimed ticket routes to the branch too — the worker's done
+  // gate has to see debt the owner files mid-claim.
+  const added = await cli(owner, "ask", `CIN-${key}`, "Also rotate the old key", "--author", "nick")
+  assert.equal(added.code, 0, added.stderr)
+  assert.ok(added.stdout.includes(`committed and pushed to ${branch}`), added.stdout)
+  assert.equal(existsSync(join(owner, ".task", "tickets", key, "asks")), false)
+  sh(verify, "git", "fetch", "--quiet", "origin", branch)
+  assert.equal(
+    sh(verify, "git", "ls-tree", "--name-only", `FETCH_HEAD:.task/tickets/${key}/asks`).split("\n").length,
+    2,
+  )
+  const again = await cli(owner, "inbox", "--json")
+  const entries = (JSON.parse(again.stdout) as { inbox: InboxEntry[] }).inbox
+  assert.deepEqual(entries[0].asks.map((a) => a.text), ["Also rotate the old key"])
+
+  // And the worker's next tick simply pulls its branch and has everything.
+  sh(worker, "git", "pull", "--quiet", "origin", branch)
+  const workerView = await cli(worker, "show", `CIN-${key}`, "--json")
+  const workerAsks = (JSON.parse(workerView.stdout) as { task: { asks: { text: string; resolvedBy: string | null }[] } }).task.asks
+  assert.deepEqual(
+    workerAsks.map((a) => [a.text, a.resolvedBy]),
+    [["Create the OAuth app in the dashboard", "nick"], ["Also rotate the old key", null]],
+  )
+})
+
+test("branch writes hold up in shallow clones and worktrees", async () => {
+  const home = tempDir()
+  const bare = join(home, "origin.git")
+  sh(home, "git", "init", "--quiet", "--bare", "-b", "main", bare)
+
+  const seed = join(home, "seed")
+  sh(home, "git", "clone", "--quiet", bare, seed)
+  sh(seed, "git", "config", "user.name", "Test")
+  sh(seed, "git", "config", "user.email", "test@example.com")
+  const store = initProject(seed, { name: "envs board", prefix: "ENV" })
+  const key = store.create({ title: "Worked while owed", status: "todo" }).key
+  const branch = `task/claim/env-${key}`
+  store.close()
+  sh(seed, "git", "add", "-A")
+  sh(seed, "git", "commit", "--quiet", "-m", "board")
+  sh(seed, "git", "push", "--quiet", "-u", "origin", "main")
+  assert.equal((await cli(seed, "claim", key)).code, 0)
+  assert.equal((await cli(seed, "ask", `ENV-${key}`, "Bless the rollout", "--author", "claude")).code, 0)
+  sh(seed, "git", "add", "-A")
+  sh(seed, "git", "commit", "--quiet", "-m", "ask")
+  sh(seed, "git", "push", "--quiet", "origin", branch)
+
+  // Shallow clone — what CI checkouts default to. The plumbing must build
+  // its commit from a fetched claim tip whose history it doesn't have.
+  const shallow = join(home, "shallow")
+  sh(home, "git", "clone", "--quiet", "--depth", "1", `file://${bare}`, shallow)
+  sh(shallow, "git", "config", "user.name", "Nick")
+  sh(shallow, "git", "config", "user.email", "nick@example.com")
+  const resolved = await cli(shallow, "resolve", `ENV-${key}`, "1", "--author", "nick")
+  assert.equal(resolved.code, 0, resolved.stderr)
+  assert.ok(resolved.stdout.includes(`committed and pushed to ${branch}`), resolved.stdout)
+
+  // Worktree — refs shared with the main checkout, index elsewhere.
+  const full = join(home, "full")
+  sh(home, "git", "clone", "--quiet", bare, full)
+  sh(full, "git", "config", "user.name", "Nick")
+  sh(full, "git", "config", "user.email", "nick@example.com")
+  const worktree = join(home, "wt")
+  sh(full, "git", "worktree", "add", "--quiet", "--detach", worktree)
+  const added = await cli(worktree, "ask", `ENV-${key}`, "Sign the SOC2 form", "--author", "nick")
+  assert.equal(added.code, 0, added.stderr)
+  assert.ok(added.stdout.includes(`committed and pushed to ${branch}`), added.stdout)
+
+  // Origin's branch carries both writes; the checkout that made them doesn't.
+  sh(full, "git", "fetch", "--quiet", "origin", branch)
+  const files = sh(full, "git", "ls-tree", "--name-only", `FETCH_HEAD:.task/tickets/${key}/asks`).split("\n")
+  assert.equal(files.length, 2)
+  assert.equal(existsSync(join(shallow, ".task", "tickets", key, "asks")), false)
+  assert.equal(existsSync(join(worktree, ".task", "tickets", key, "asks")), false)
+})