@nickmeriano/task 0.7.1 → 0.9.0

package/src/git.ts

@@ -0,0 +1,141 @@
+/**
+ * Every git spawn in the CLI goes through here (TAS-40, folded into TAS-42):
+ * one place that guarantees a spawn can never wedge the process. Each call is
+ * non-interactive — `GIT_TERMINAL_PROMPT=0` turns a would-be credential
+ * prompt into a fast failure — and bounded by a timeout, because several of
+ * these run inside `task serve` request handlers, where a hung prompt or a
+ * wedged remote would hang the board for everyone looking at it.
+ *
+ * Three calling styles, because callers genuinely differ on what failure is:
+ * `git` returns the full result (claim flows branch on exit codes), `gitMust`
+ * throws (steps with no soft outcome), `gitOut` returns null (read paths that
+ * degrade to "can't ask git" — the serve/inbox rule).
+ */
+
+import { spawnSync } from "node:child_process"
+
+export interface GitResult {
+  status: number
+  stdout: string
+  stderr: string
+}
+
+export interface GitOptions {
+  /** Extra env on top of the non-interactive baseline — e.g. GIT_INDEX_FILE. */
+  env?: Record<string, string>
+  /** Piped to stdin — e.g. `hash-object -w --stdin`. */
+  input?: string
+  timeoutMs?: number
+}
+
+/** Local operations answer fast or something is genuinely wrong. */
+export const GIT_TIMEOUT_MS = 30_000
+/** Network operations (a full fetch, a push) get real-world headroom. */
+export const GIT_NETWORK_TIMEOUT_MS = 120_000
+
+/**
+ * The one spawn. A failed spawn (git missing, timeout hit) reads as status 1
+ * with the reason in stderr — callers treat it exactly like a failed command,
+ * which for every caller here is the truth that matters.
+ */
+export function runGit(cwd: string, args: string[], options: GitOptions = {}): GitResult {
+  const result = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    input: options.input,
+    timeout: options.timeoutMs ?? GIT_TIMEOUT_MS,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0", ...options.env },
+  })
+  if (result.error) {
+    return { status: 1, stdout: "", stderr: result.error.message }
+  }
+  return {
+    status: result.status ?? 1,
+    stdout: (result.stdout ?? "").trim(),
+    stderr: (result.stderr ?? "").trim(),
+  }
+}
+
+export function git(cwd: string, ...args: string[]): GitResult {
+  return runGit(cwd, args)
+}
+
+/** Run git and throw on failure — for the steps that have no soft outcome. */
+export function gitMust(cwd: string, ...args: string[]): string {
+  const result = runGit(cwd, args)
+  if (result.status !== 0) {
+    throw new Error(`git ${args[0]} failed: ${result.stderr || result.stdout}`)
+  }
+  return result.stdout
+}
+
+/** Soft git: stdout on success, null on any failure — callers decide if that's an error. */
+export function gitOut(cwd: string, ...args: string[]): string | null {
+  const result = runGit(cwd, args)
+  return result.status === 0 ? result.stdout : null
+}
+
+/**
+ * The base a claim or board branch starts from: origin's default branch.
+ * Resolved from `origin/HEAD` when the clone recorded it, with a main/master
+ * fallback for repos wired up by hand (`git remote add` + push never sets
+ * origin/HEAD).
+ */
+export function defaultBase(cwd: string): string {
+  const head = git(cwd, "symbolic-ref", "--quiet", "refs/remotes/origin/HEAD")
+  if (head.status === 0) return head.stdout.replace(/^refs\/remotes\//, "")
+  for (const name of ["main", "master"]) {
+    if (git(cwd, "show-ref", "--verify", "--quiet", `refs/remotes/origin/${name}`).status === 0) {
+      return `origin/${name}`
+    }
+  }
+  throw new Error(
+    "couldn't resolve origin's default branch — origin/HEAD is unset and neither origin/main nor origin/master exists",
+  )
+}
+
+// ── Remote identity ──────────────────────────────────────────────────────────
+
+export interface RepoRef {
+  owner: string
+  repo: string
+}
+
+/**
+ * The GitHub repo this working copy pushes to.
+ *
+ * `origin` first, then the only remote if there's exactly one — a clone with
+ * `upstream` and a fork remote should not silently pick the wrong one, so
+ * ambiguity reads as "no repo" and the caller asks the user.
+ */
+export function detectRepo(cwd: string): RepoRef | null {
+  const remotes = gitRemotes(cwd)
+  const url = remotes.get("origin") ?? (remotes.size === 1 ? [...remotes.values()][0] : null)
+  return url ? parseRemote(url) : null
+}
+
+function gitRemotes(cwd: string): Map<string, string> {
+  const out = new Map<string, string>()
+  const raw = gitOut(cwd, "remote", "-v")
+  if (raw === null) return out
+  for (const line of raw.split("\n")) {
+    const match = /^(\S+)\s+(\S+)\s+\(fetch\)$/.exec(line.trim())
+    if (match) out.set(match[1], match[2])
+  }
+  return out
+}
+
+/**
+ * Every shape git writes a GitHub remote in: https, ssh, `git@`-scp, with or
+ * without `.git`, and with or without credentials embedded in the host.
+ */
+export function parseRemote(url: string): RepoRef | null {
+  const cleaned = url.trim().replace(/\.git$/, "")
+  const match =
+    /^(?:https?:\/\/|ssh:\/\/)?(?:[^@/]+@)?github\.com[:/]([^/]+)\/([^/]+?)\/?$/.exec(cleaned)
+  if (!match) return null
+  const [, owner, repo] = match
+  if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/.test(owner)) return null
+  if (!/^[A-Za-z0-9._-]{1,100}$/.test(repo)) return null
+  return { owner, repo }
+}

package/src/id.ts

@@ -0,0 +1,68 @@
+/**
+ * Ticket keys — the branch-safe identity scheme (TAS-42).
+ *
+ * A ticket's key is 5 random characters from a 27-letter alphabet, minted at
+ * `task add` with no coordination: two checkouts that have never seen each
+ * other's commits can't mint the same key except by 1-in-14M chance per pair,
+ * and `task check`'s duplicate lint catches the miracle at merge. The key IS
+ * the ticket's directory name under `.task/tickets/`, so allocation is safe by
+ * construction — git can't merge two different tickets into one directory.
+ *
+ * The alphabet drops vowels (keys can't spell words), 0/1/i/l/o/u (no
+ * confusable glyphs when a key is read aloud or typed from a screen), and is
+ * all-lowercase (keys land in claim branch names, which are case-sensitive
+ * refs). A key always contains a letter — an all-digit roll is re-rolled — so
+ * a purely numeric directory is unambiguously a pre-migration ticket, which
+ * is exactly how the check lint tells the two apart.
+ *
+ * Keys deliberately carry no timestamp and no sequence: identity must be
+ * dumber than metadata. Creation order lives in `created:`; board order lives
+ * in `position:`. Anything the key "said" beyond naming the ticket could be
+ * wrong one day, and a wrong id breaks every reference to it.
+ */
+
+export const KEY_ALPHABET = "23456789bcdfghjkmnpqrstvwxz"
+export const KEY_LENGTH = 5
+
+/**
+ * What a ticket key may look like — the shape readers accept, wider than what
+ * minting produces so a future length change doesn't strand old boards. Must
+ * contain a letter: an all-digit name is a pre-migration ticket number, and
+ * the two must never be confusable.
+ */
+export const KEY_PATTERN = /^(?=.*[a-z])[a-z0-9]{4,12}$/
+
+export function isTicketKey(value: string): boolean {
+  return KEY_PATTERN.test(value)
+}
+
+/**
+ * One random roll — Web Crypto (global in Node ≥19 and in Workers, so this
+ * module stays importable by the hosted board), with rejection sampling so
+ * the 27-letter alphabet gets a uniform draw rather than a modulo bias.
+ */
+function roll(): string {
+  const limit = 256 - (256 % KEY_ALPHABET.length)
+  let key = ""
+  while (key.length < KEY_LENGTH) {
+    const bytes = crypto.getRandomValues(new Uint8Array(KEY_LENGTH * 2))
+    for (const byte of bytes) {
+      if (byte >= limit || key.length >= KEY_LENGTH) continue
+      key += KEY_ALPHABET[byte % KEY_ALPHABET.length]
+    }
+  }
+  return key
+}
+
+/**
+ * Mint a key no ticket on this checkout uses. The local-collision retry is
+ * near-free insurance; the cross-branch case has no lock by design and rides
+ * on the odds (27^5 ≈ 14M keys) plus the check lint.
+ */
+export function mintKey(taken: ReadonlySet<string>): string {
+  for (;;) {
+    const key = roll()
+    if (!KEY_PATTERN.test(key)) continue // all-digit roll — must stay pre-migration-only
+    if (!taken.has(key)) return key
+  }
+}

package/src/inbox.ts

@@ -0,0 +1,77 @@
+/**
+ * `task inbox` — every open ask on effectively-in-progress tickets, repo-wide.
+ * The one list a person checks to unblock work NOW (TAS-38): each entry is a
+ * stalled worker or stalled work, nothing else.
+ *
+ * "Effectively in progress" is TAS-26's read core: between claim and merge the
+ * default branch still says `todo` — the claim branch is the truth about
+ * in-flight work, and the branch *name* carries the ticket id, so resolving it
+ * costs one fetch of the claim refs, never a general branch scan. The asks a
+ * worker files mid-run live on its claim branch too, so the inbox reads each
+ * claimed ticket's ask files from the branch and unions them with the local
+ * ones by id (asks are one file each, so the union is exact; see claim-io.ts,
+ * which also owns the write side of the same rule). Offline, or with no
+ * origin at all, everything degrades silently to file truth — a board you
+ * can't fetch is still a board.
+ *
+ * Backlog and todo asks are deliberately out of scope: unstarted work owes
+ * nobody anything yet, and claiming is what promotes an ask into the inbox.
+ */
+
+import { claimBranch, claimNamespace } from "./claim.ts"
+import { mergedAsks, remoteClaimTips, syncClaimRefs } from "./claim-io.ts"
+import type { Store } from "./store.ts"
+import type { Ask, Task } from "./types.ts"
+
+/** A board handed to buildInbox: the store plus the id the UI navigates with. */
+export interface InboxBoard {
+  /** Path relative to the repo's board scope — "." for the root board. */
+  id: string
+  store: Store
+}
+
+export interface InboxEntry {
+  board: string
+  prefix: string
+  /** File truth — a claimed ticket may still read `todo` here; `claim` says why it counts. */
+  task: Task
+  /** Present when the ticket's claim branch exists on origin. */
+  claim: { branch: string } | null
+  /** Open asks only, oldest first; ordinals match `task show`'s (the union's, when claimed). */
+  asks: Ask[]
+}
+
+/** Oldest open ask decides an entry's urgency — and the whole list's order. */
+function oldestAsk(entry: InboxEntry): string {
+  return entry.asks[0]?.createdAt ?? ""
+}
+
+export function buildInbox(boards: InboxBoard[]): InboxEntry[] {
+  const entries: InboxEntry[] = []
+  for (const { id, store } of boards) {
+    // One bounded ls-remote per board; branches are then fetched only when
+    // their tip moved (syncClaimRefs), so a refetch-happy UI costs one round
+    // trip, not a fetch storm. Null = origin unreachable = file truth only.
+    const tips = remoteClaimTips(store)
+    const claimed = tips ? new Set(tips.keys()) : null
+    if (tips && tips.size > 0) {
+      try {
+        syncClaimRefs(store, claimNamespace(store.config), tips)
+      } catch {
+        // Namespace validated by remoteClaimTips already; nothing to do.
+      }
+    }
+    // in_progress is in by file truth; todo is in only via a live claim.
+    for (const task of store.list({ statuses: ["in_progress", "todo"] })) {
+      const branch = claimBranch(store.config, task.key)
+      const claim = claimed?.has(branch) ? { branch } : null
+      if (task.status !== "in_progress" && !claim) continue
+      const asks = (claim ? mergedAsks(store, branch, task) : task.asks).filter(
+        (a) => !a.resolvedAt,
+      )
+      if (asks.length === 0) continue
+      entries.push({ board: id, prefix: store.config.prefix, task, claim, asks })
+    }
+  }
+  return entries.sort((a, b) => oldestAsk(a).localeCompare(oldestAsk(b)))
+}

package/src/index.ts

@@ -1,7 +1,6 @@
 // Programmatic access to the same store the CLI and `task serve` use — for
 // scripts that want to read or write .task/ without shelling out.
 export {
-  TaskStore,
   boardConfig,
   derivePrefix,
   findBoards,
@@ -16,17 +15,20 @@ export {
   FileStore,
   TICKETS_DIR,
   initProject,
-  migrateBoard,
   openBoard,
 } from "./file-store.ts"
 export {
   parseTicket,
+  parseTicketLenient,
   serializeTicket,
   parseComment,
+  parseCommentLenient,
   serializeComment,
   type TicketDoc,
   type CommentDoc,
 } from "./ticket-doc.ts"
+export { checkBoards, checkRoot, type CheckIssue, type CheckResult } from "./check.ts"
+export { searchStore, type SearchMatch, type SearchResult } from "./search.ts"
 export {
   DEFAULT_CLAIM_PREFIX,
   ClaimError,

package/src/overview.test.ts

@@ -0,0 +1,52 @@
+/**
+ * `task overview` derives everything at read time — these tests pin the
+ * derivations: per-status counts, per-goal progress, needs-human, staleness
+ * against an injected clock, oldest-open, and the "unknown, not zero" answer
+ * for claims when there is no origin to ask.
+ */
+
+import assert from "node:assert/strict"
+import { test } from "node:test"
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { initProject } from "./file-store.ts"
+import { STALE_DAYS, buildOverview } from "./overview.ts"
+
+function tempRoot(): string {
+  const dir = mkdtempSync(join(tmpdir(), "task-overview-"))
+  process.on("exit", () => rmSync(dir, { recursive: true, force: true }))
+  return dir
+}
+
+test("overview derives board health at read time", () => {
+  const root = tempRoot()
+  const store = initProject(root, { name: "health", prefix: "HLT" })
+  store.createGoal({ title: "Launch" })
+  const a = store.create({ title: "Oldest", status: "todo", goal: "launch" })
+  const b = store.create({ title: "Shipped", status: "todo", goal: "launch" })
+  store.update(b.key, { status: "done" })
+  const person = store.create({ title: "Waiting on a person", status: "todo" })
+  store.addAsk(person.key, "Sign the SOC2 form", "claude")
+  store.create({ title: "Still parked", status: "backlog" })
+
+  // Age the first ticket by hand — the store always writes "now".
+  const ticketPath = join(root, ".task", "tickets", a.key, "ticket.md")
+  const aged = readFileSync(ticketPath, "utf8")
+    .replace(/created: .*/, "created: 2020-01-01T00:00:00.000Z")
+    .replace(/updated: .*/, "updated: 2020-01-01T00:00:00.000Z")
+  writeFileSync(ticketPath, aged)
+
+  const overview = buildOverview(store, Date.parse("2020-01-10T00:00:00.000Z") + STALE_DAYS * 86_400_000)
+  assert.equal(overview.board, "health")
+  assert.equal(overview.prefix, "HLT")
+  assert.deepEqual(overview.statuses, { backlog: 1, todo: 2, in_progress: 0, done: 1, canceled: 0 })
+  assert.equal(overview.open, 3)
+  assert.equal(overview.needsHuman, 1)
+  // No origin to ask — unknown, not zero.
+  assert.equal(overview.claimed, null)
+  assert.deepEqual(overview.goals, [{ slug: "launch", title: "Launch", done: 1, total: 2 }])
+  // Only the aged ticket is stale at that clock (the others were written just now).
+  assert.deepEqual(overview.stale.map((t) => t.id), [a.id])
+  assert.equal(overview.oldestOpen?.id, a.id)
+})

package/src/overview.ts

@@ -0,0 +1,105 @@
+/**
+ * `task overview` — one screen of board health (TAS-27): the numbers an agent
+ * wants before choosing work and the numbers a human wants in a standup.
+ * Nothing configurable, no charts, and nothing stored — every figure is
+ * derived from the board at read time, the same rule goals follow.
+ */
+
+import { claimBranch } from "./claim.ts"
+import { remoteClaimTips } from "./claim-io.ts"
+import type { Store } from "./store.ts"
+import { STATUSES, type Status } from "./types.ts"
+
+/** Untouched this long, an open ticket is stale. Fixed on purpose. */
+export const STALE_DAYS = 14
+
+const OPEN_STATUSES: readonly Status[] = ["backlog", "todo", "in_progress"]
+
+export interface GoalProgress {
+  slug: string
+  title: string
+  done: number
+  total: number
+}
+
+export interface TicketRef {
+  id: string
+  title: string
+}
+
+export interface Overview {
+  board: string
+  prefix: string
+  /** Live board only — the archive is history, not health. */
+  statuses: Record<Status, number>
+  open: number
+  /** Open tickets a person owes something — i.e. carrying open asks. */
+  needsHuman: number
+  /** Open asks across the live board's open tickets. */
+  openAsks: number
+  /** The ask that's been owed longest — the standup's guilty number. */
+  oldestAsk: { taskId: string; text: string; createdAt: string } | null
+  /**
+   * Open tickets whose claim branch exists on origin right now; null when
+   * origin can't be asked (no remote, offline) — unknown, not zero.
+   */
+  claimed: string[] | null
+  goals: GoalProgress[]
+  /** Open tickets untouched for STALE_DAYS+, oldest first. */
+  stale: (TicketRef & { updatedAt: string })[]
+  oldestOpen: (TicketRef & { createdAt: string }) | null
+}
+
+export function buildOverview(store: Store, now: number = Date.now()): Overview {
+  const tasks = store.list({ statuses: undefined })
+  const statuses = Object.fromEntries(STATUSES.map((s) => [s, 0])) as Record<Status, number>
+  for (const task of tasks) statuses[task.status]++
+  const open = tasks.filter((t) => OPEN_STATUSES.includes(t.status))
+
+  // The bounded read — a board health check must never hang on a credential
+  // prompt; unreachable origin reads as "claimed ?" (null), not zero.
+  const tips = remoteClaimTips(store)
+  const claimed = tips
+    ? open.filter((t) => tips.has(claimBranch(store.config, t.key))).map((t) => t.id)
+    : null
+
+  const goals = store.goals().map((goal) => {
+    const mine = tasks.filter((t) => t.goal === goal.slug)
+    const done = mine.filter((t) => t.status === "done" || t.status === "canceled").length
+    return { slug: goal.slug, title: goal.title, done, total: mine.length }
+  })
+
+  const staleBefore = now - STALE_DAYS * 24 * 60 * 60 * 1000
+  const stale = open
+    .filter((t) => Date.parse(t.updatedAt) < staleBefore)
+    .sort((a, b) => Date.parse(a.updatedAt) - Date.parse(b.updatedAt))
+    .map((t) => ({ id: t.id, title: t.title, updatedAt: t.updatedAt }))
+
+  const oldest = [...open].sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt))[0]
+
+  const openAsks = open
+    .flatMap((t) => t.asks.filter((a) => !a.resolvedAt).map((a) => ({ taskId: t.id, ask: a })))
+    .sort((a, b) => a.ask.createdAt.localeCompare(b.ask.createdAt))
+
+  return {
+    board: store.config.name,
+    prefix: store.config.prefix,
+    statuses,
+    open: open.length,
+    needsHuman: open.filter((t) => t.needsHuman).length,
+    openAsks: openAsks.length,
+    oldestAsk: openAsks[0]
+      ? {
+          taskId: openAsks[0].taskId,
+          text: openAsks[0].ask.text,
+          createdAt: openAsks[0].ask.createdAt,
+        }
+      : null,
+    claimed,
+    goals,
+    stale,
+    oldestOpen: oldest
+      ? { id: oldest.id, title: oldest.title, createdAt: oldest.createdAt }
+      : null,
+  }
+}

package/src/promote.test.ts

@@ -0,0 +1,143 @@
+/**
+ * `task promote` — from the outside (real CLI subprocesses, exit codes are
+ * the contract):
+ *
+ * 1. Any backlog ticket promotes to todo, exit 0 — there is no quality gate;
+ *    planning happens at claim time.
+ * 2. Only backlog tickets promote — todo/in_progress/done are refused.
+ * 3. Blocked tickets still promote, with the hold reported (stdout note,
+ *    `holds` in --json) — blockers are claim-time gates. Needs-human isn't
+ *    one at all anymore: asks gate done, not claiming.
+ * 4. `task add` with no --status lands in backlog: the dump list is the
+ *    default, todo is the deliberate choice promote makes.
+ */
+
+import assert from "node:assert/strict"
+import { test } from "node:test"
+import { execFile } from "node:child_process"
+import { mkdtempSync, rmSync, writeFileSync } 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 { Task } from "./types.ts"
+
+const CLI = fileURLToPath(new URL("./cli.ts", import.meta.url))
+
+function tempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "task-promote-test-"))
+  process.on("exit", () => rmSync(dir, { recursive: true, force: true }))
+  return dir
+}
+
+interface CliResult {
+  code: number
+  stdout: string
+  stderr: string
+}
+
+/** The CLI as callers see it — a subprocess with an exit code. */
+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 })
+      },
+    )
+  })
+}
+
+/**
+ * A board with every promotion shape. Promotion never touches git, so a bare
+ * .task/ directory is the whole fixture:
+ *   liner   "One-liner"      backlog (no tags — nothing else required)
+ *   also    "Also backlog"   backlog
+ *   blocked "Blocked"        backlog, blocked by `also`
+ *   person  "For a person"   backlog, carrying an open ask
+ *   queued  "Already queued" todo
+ */
+interface Fixture {
+  dir: string
+  ids: { liner: string; also: string; blocked: string; person: string; queued: string }
+}
+
+function fixture(): Fixture {
+  const dir = tempDir()
+  const store = initProject(dir, { name: "promote board", prefix: "PRO" })
+  const liner = store.create({ title: "One-liner", status: "backlog" })
+  const also = store.create({ title: "Also backlog", status: "backlog" })
+  const blocked = store.create({ title: "Blocked", status: "backlog", blockedBy: [also.key] })
+  const person = store.create({ title: "For a person", status: "backlog" })
+  store.addAsk(person.key, "Pick the vendor", "claude")
+  const queued = store.create({ title: "Already queued", status: "todo" })
+  store.close()
+  return {
+    dir,
+    ids: { liner: liner.id, also: also.id, blocked: blocked.id, person: person.id, queued: queued.id },
+  }
+}
+
+async function show(dir: string, id: string): Promise<Task> {
+  const result = await cli(dir, "show", id, "--json")
+  assert.equal(result.code, 0, result.stderr)
+  return (JSON.parse(result.stdout) as { task: Task }).task
+}
+
+test("any backlog ticket promotes to todo — no quality gate", async () => {
+  const { dir, ids } = fixture()
+  const result = await cli(dir, "promote", ids.liner, "--json")
+  assert.equal(result.code, 0, result.stderr)
+  const { task, holds } = JSON.parse(result.stdout) as { task: Task; holds: string[] }
+  assert.equal(task.status, "todo")
+  assert.deepEqual(holds, [])
+  assert.equal((await show(dir, ids.liner)).status, "todo")
+})
+
+test("only backlog tickets promote", async () => {
+  const { dir, ids } = fixture()
+  const result = await cli(dir, "promote", ids.queued)
+  assert.equal(result.code, 2)
+  assert.match(result.stderr, /is todo — only backlog tickets/)
+})
+
+test("blocked tickets promote with the hold reported; needs-human isn't a hold", async () => {
+  const { dir, ids } = fixture()
+  const blocked = await cli(dir, "promote", ids.blocked, "--json")
+  assert.equal(blocked.code, 0, blocked.stderr)
+  const parsed = JSON.parse(blocked.stdout) as { task: Task; holds: string[] }
+  assert.equal(parsed.task.status, "todo")
+  assert.deepEqual(parsed.holds, [`blocked by ${ids.also}`])
+
+  // Asks gate done, not claiming — so a human-owing ticket promotes with
+  // nothing to report.
+  const person = await cli(dir, "promote", ids.person, "--json")
+  assert.equal(person.code, 0, person.stderr)
+  assert.deepEqual((JSON.parse(person.stdout) as { holds: string[] }).holds, [])
+  assert.equal((await show(dir, ids.person)).status, "todo")
+})
+
+test("task add with no --status lands in backlog", async () => {
+  const { dir } = fixture()
+  const added = await cli(dir, "add", "Dumped in passing", "--json")
+  assert.equal(added.code, 0, added.stderr)
+  const { task } = JSON.parse(added.stdout) as { task: Task }
+  assert.equal(task.status, "backlog")
+})
+
+test("--description-file reads markdown from disk; combining both flags refuses", async () => {
+  const { dir } = fixture()
+  const body = "## Plan\n\nA description with \"quotes\", `backticks`,\nand $(subshells) that never touch a shell.\n"
+  writeFileSync(join(dir, "desc.md"), body)
+
+  const added = await cli(dir, "add", "From a file", "--description-file", "desc.md", "--json")
+  assert.equal(added.code, 0, added.stderr)
+  const { task } = JSON.parse(added.stdout) as { task: Task }
+  assert.match(task.description ?? "", /"quotes", `backticks`,\nand \$\(subshells\)/)
+
+  const both = await cli(dir, "update", task.id, "--description", "x", "--description-file", "desc.md")
+  assert.equal(both.code, 1)
+  assert.match(both.stderr, /not both/)
+})