@nickmeriano/task 0.8.0 → 0.10.0

package/src/server.ts

@@ -3,8 +3,11 @@ import { watch, existsSync, readFileSync, statSync, type FSWatcher } from "node:
 import { extname, join, normalize } from "node:path"
 import { fileURLToPath } from "node:url"
 import { resolveAuthor } from "./author.ts"
+import { addAskRouted, deleteAskRouted, setAskResolvedRouted } from "./claim-io.ts"
 import { openBoard } from "./file-store.ts"
-import { findBoards, type BoardRef, type Store } from "./store.ts"
+import { GitServe, GitServeError } from "./git-serve.ts"
+import { buildInbox } from "./inbox.ts"
+import { boardConfig, findBoards, type BoardRef, type Store } from "./store.ts"
 import { STATUSES, isStatus, type TaskPatch } from "./types.ts"
 
 /** The prebuilt SPA, shipped inside the package next to dist/. */
@@ -48,9 +51,8 @@ function parsePatch(body: Record<string, unknown>): TaskPatch {
   if (typeof body.goal === "string" || body.goal === null) {
     patch.goal = body.goal === "" ? null : body.goal
   }
-  if (typeof body.needsHuman === "boolean") patch.needsHuman = body.needsHuman
-  if (Array.isArray(body.blocks)) patch.blocks = body.blocks.map(taskNumber)
-  if (Array.isArray(body.blockedBy)) patch.blockedBy = body.blockedBy.map(taskNumber)
+  if (Array.isArray(body.blocks)) patch.blocks = body.blocks.map(taskKey)
+  if (Array.isArray(body.blockedBy)) patch.blockedBy = body.blockedBy.map(taskKey)
   if (Array.isArray(body.prs)) {
     patch.prs = body.prs.map((pr) => {
       const url = String(pr).trim()
@@ -63,10 +65,32 @@ function parsePatch(body: Record<string, unknown>): TaskPatch {
   return patch
 }
 
-function taskNumber(value: unknown): number {
-  const n = Number(value)
-  if (!Number.isInteger(n) || n <= 0) throw new Error(`invalid task number: ${String(value)}`)
-  return n
+function taskKey(value: unknown): string {
+  if (typeof value !== "string" || !/^[a-z0-9]+$/.test(value)) {
+    throw new Error(`invalid task key: ${String(value)}`)
+  }
+  return value
+}
+
+/**
+ * The CSRF gate. `task serve` is an unauthenticated HTTP server, and any
+ * webpage in the same browser can aim a POST at it — before this check, a
+ * drive-by page could edit the board, and with the git surface it could
+ * commit and push. Same-origin is the whole auth model, so a write has to
+ * prove it: browsers attach `Origin` to every cross-origin request (and to
+ * all fetch POSTs), and the only origin allowed to write is the board's own —
+ * whatever host the request itself was addressed to. No Origin header means
+ * no browser page is speaking (curl, scripts), which is the local-trust case
+ * the server already accepts.
+ */
+function sameOrigin(req: IncomingMessage): boolean {
+  const origin = req.headers.origin
+  if (origin === undefined) return true
+  try {
+    return new URL(origin).host === req.headers.host
+  } catch {
+    return false // "null" and other unparseable origins are nobody we trust
+  }
 }
 
 /**
@@ -144,6 +168,28 @@ export function createTaskServer(serveRoot: string): Server {
     throw new Error(`no .task directory found at or below ${serveRoot} — run \`task init\` first`)
   }
 
+  const gitServe = new GitServe(serveRoot, () =>
+    ordered.map((id) => ({ id, store: boards.get(id)!.store })),
+  )
+
+  // Branch switches don't touch `.task/` files, but they change what every
+  // board file *says* — so watch the git dir for HEAD moving (a checkout,
+  // from this server or a terminal) and ping every board's SSE listeners.
+  // Non-recursive on the resolved git dir (worktrees keep HEAD there), and
+  // best-effort: a repo this can't watch simply refreshes on the next edit.
+  let gitWatcher: FSWatcher | null = null
+  const gitDir = gitServe.gitDir()
+  if (gitDir) {
+    try {
+      gitWatcher = watch(gitDir, (_event, filename) => {
+        if (filename === "HEAD") for (const id of ordered) noteChange(id)
+      })
+      gitWatcher.on("error", () => {})
+    } catch {
+      gitWatcher = null
+    }
+  }
+
   const heartbeat = setInterval(() => {
     for (const client of clients) client.write(`: ping\n\n`)
   }, 30_000)
@@ -159,6 +205,7 @@ export function createTaskServer(serveRoot: string): Server {
   server.on("close", () => {
     if (pending) clearTimeout(pending)
     clearInterval(heartbeat)
+    gitWatcher?.close()
     for (const board of boards.values()) {
       board.watcher.close()
       board.store.close()
@@ -170,6 +217,19 @@ export function createTaskServer(serveRoot: string): Server {
     const url = new URL(req.url ?? "/", "http://localhost")
     const path = url.pathname
 
+    // Every mutation, one gate — the ask routes push commits and the git
+    // routes run git, so this cannot be per-endpoint courtesy.
+    const method = req.method ?? "GET"
+    if (
+      path.startsWith("/api/") &&
+      method !== "GET" &&
+      method !== "HEAD" &&
+      !sameOrigin(req)
+    ) {
+      json(res, 403, { error: "cross-origin request refused — the board only writes for its own pages" })
+      return
+    }
+
     if (path === "/api/events") {
       res.writeHead(200, {
         "Content-Type": "text/event-stream",
@@ -193,6 +253,94 @@ export function createTaskServer(serveRoot: string): Server {
       return
     }
 
+    if (path === "/api/inbox") {
+      // Deliberately cross-board — the header badge is repo-wide attention.
+      // Scope follows the CLI's selection rule: the root board's `boards`
+      // list when it has one (matched by prefix), every served board
+      // otherwise — so a vendored board can't put asks in your face unless
+      // the root board opted it in.
+      syncBoards()
+      const all = ordered.map((id) => ({ id, store: boards.get(id)!.store }))
+      let scoped = all
+      try {
+        const wanted = boardConfig(all[0].store.root).boards
+        if (Array.isArray(wanted) && wanted.length > 0) {
+          const prefixes = new Set(wanted.map((p) => String(p).toUpperCase()))
+          const matched = all.filter((b) => prefixes.has(b.store.config.prefix.toUpperCase()))
+          if (matched.length > 0) scoped = matched
+        }
+      } catch {
+        // Unreadable root config — serve everything rather than nothing.
+      }
+      json(res, 200, { inbox: buildInbox(scoped) })
+      return
+    }
+
+    // The git surface (TAS-42). Repo-level, not board-level — one working
+    // tree holds every served board — so it lives beside /api/inbox rather
+    // than inside routeApi. Every handler 404s ("no git surface here") when
+    // the capability is off, which is also what the prebuilt UI probes.
+    if (path.startsWith("/api/git/")) {
+      const fail = (error: unknown): void => {
+        const status = error instanceof GitServeError ? error.status : 400
+        json(res, status, { error: error instanceof Error ? error.message : String(error) })
+      }
+      try {
+        if (path === "/api/git/status" && req.method === "GET") {
+          json(res, 200, gitServe.status())
+          return
+        }
+        if (path === "/api/git/branches" && req.method === "GET") {
+          json(res, 200, { branches: gitServe.branches() })
+          return
+        }
+        if (path === "/api/git/pr" && req.method === "GET") {
+          const branch = url.searchParams.get("branch")
+          if (!branch) {
+            json(res, 400, { error: "branch is required" })
+            return
+          }
+          json(res, 200, gitServe.prFor(branch))
+          return
+        }
+        if (path === "/api/git/commit" && req.method === "POST") {
+          void readBody(req)
+            .then((body) => json(res, 200, gitServe.commit(body)))
+            .catch(fail)
+          return
+        }
+        if (path === "/api/git/checkout" && req.method === "POST") {
+          void readBody(req)
+            .then((body) => json(res, 200, gitServe.checkout(body)))
+            .catch(fail)
+          return
+        }
+        if (path === "/api/git/pr" && req.method === "POST") {
+          void readBody(req)
+            .then((body) => json(res, 200, gitServe.pr(body)))
+            .catch(fail)
+          return
+        }
+        if (path === "/api/git/release" && req.method === "POST") {
+          const id = url.searchParams.get("board") ?? ordered[0]
+          const board = boards.get(id)
+          if (!board) {
+            json(res, 404, { error: `no such board: ${id}` })
+            return
+          }
+          void readBody(req)
+            .then((body) => json(res, 200, gitServe.releaseClaim(board.store, body, author)))
+            .catch(fail)
+          return
+        }
+      } catch (error) {
+        fail(error)
+        return
+      }
+      json(res, 404, { error: "not found" })
+      return
+    }
+
     if (path.startsWith("/api/")) {
       const id = url.searchParams.get("board") ?? ordered[0]
       const board = boards.get(id)
@@ -219,6 +367,10 @@ export function createTaskServer(serveRoot: string): Server {
         prefix: store.config.prefix,
         statuses: STATUSES,
         author,
+        // The git capability, or nothing: its absence is how the hosted and
+        // snapshot deployments (whose /project never carries it) and a serve
+        // with no origin all tell the UI to draw no git surface at all.
+        git: gitServe.capability() ?? undefined,
       })
       return
     }
@@ -236,7 +388,7 @@ export function createTaskServer(serveRoot: string): Server {
       const counts = store.commentCounts()
       const tasks = store
         .list()
-        .map((t) => ({ ...t, commentCount: counts.get(t.number) ?? 0 }))
+        .map((t) => ({ ...t, commentCount: counts.get(t.key) ?? 0 }))
       json(res, 200, { tasks })
       return
     }
@@ -248,19 +400,69 @@ export function createTaskServer(serveRoot: string): Server {
             throw new Error("title is required")
           }
           const patch = parsePatch(body)
-          const task = store.create({ title: body.title.trim(), ...patch })
+          let task = store.create({ title: body.title.trim(), ...patch })
+          // Asks at create time — the dialog's chip. Author is the server's
+          // resolved identity, same trust rule as comments.
+          if (Array.isArray(body.asks)) {
+            for (const text of body.asks) {
+              if (typeof text === "string" && text.trim()) {
+                store.addAsk(task.key, text.trim(), author)
+              }
+            }
+            task = store.get(task.key)!
+          }
           json(res, 201, { task })
         })
         .catch((error: Error) => json(res, 400, { error: error.message }))
       return
     }
 
+    // Routed, not raw store calls: on a claimed ticket the write lands on the
+    // claim branch as a pushed commit (claim-io.ts) — the branch owns a
+    // claimed ticket's asks, checkbox and CLI alike.
+    const askMatch = /^\/api\/tasks\/([^/]+)\/asks(?:\/([^/]+))?$/.exec(path)
+    if (askMatch) {
+      const key = store.parseId(decodeURIComponent(askMatch[1]))
+      if (!askMatch[2] && req.method === "POST") {
+        void readBody(req)
+          .then((body) => {
+            if (typeof body.text !== "string" || !body.text.trim()) {
+              throw new Error("text is required")
+            }
+            const { ask, branch } = addAskRouted(store, key, body.text.trim(), author)
+            json(res, 201, { ask, branch })
+          })
+          .catch((error: Error) => json(res, 400, { error: error.message }))
+        return
+      }
+      if (askMatch[2] && req.method === "PATCH") {
+        const ref = decodeURIComponent(askMatch[2])
+        void readBody(req)
+          .then((body) => {
+            if (typeof body.resolved !== "boolean") {
+              throw new Error("resolved must be true or false")
+            }
+            const { ask, branch } = setAskResolvedRouted(store, key, ref, body.resolved, author)
+            json(res, 200, { ask, branch })
+          })
+          .catch((error: Error) => json(res, 400, { error: error.message }))
+        return
+      }
+      if (askMatch[2] && req.method === "DELETE") {
+        const { branch } = deleteAskRouted(store, key, decodeURIComponent(askMatch[2]))
+        json(res, 200, { ok: true, branch })
+        return
+      }
+      json(res, 404, { error: "not found" })
+      return
+    }
+
     const taskMatch = /^\/api\/tasks\/([^/]+)(\/comments(?:\/([^/]+))?)?$/.exec(path)
     if (taskMatch) {
-      const number = store.parseId(decodeURIComponent(taskMatch[1]))
+      const key = store.parseId(decodeURIComponent(taskMatch[1]))
       if (taskMatch[3] && req.method === "DELETE") {
         const commentId = decodeURIComponent(taskMatch[3])
-        const existing = store.comments(number).find((c) => c.id === commentId)
+        const existing = store.comments(key).find((c) => c.id === commentId)
         if (!existing) {
           json(res, 404, { error: `no such comment: ${commentId}` })
           return
@@ -271,7 +473,7 @@ export function createTaskServer(serveRoot: string): Server {
           json(res, 403, { error: "only your own comments can be deleted" })
           return
         }
-        store.deleteComment(number, commentId)
+        store.deleteComment(key, commentId)
         json(res, 200, { ok: true })
         return
       }
@@ -282,7 +484,7 @@ export function createTaskServer(serveRoot: string): Server {
               throw new Error("body is required")
             }
             // `body.author` is ignored on purpose — unauthenticated noise.
-            const comment = store.addComment(number, body.body.trim(), author)
+            const comment = store.addComment(key, body.body.trim(), author)
             json(res, 201, { comment })
           })
           .catch((error: Error) => json(res, 400, { error: error.message }))
@@ -290,25 +492,25 @@ export function createTaskServer(serveRoot: string): Server {
       }
       if (!taskMatch[2]) {
         if (req.method === "GET") {
-          const task = store.get(number)
+          const task = store.get(key)
           if (!task) {
-            json(res, 404, { error: `no such task: ${store.displayId(number)}` })
+            json(res, 404, { error: `no such task: ${store.displayId(key)}` })
             return
           }
-          json(res, 200, { task, comments: store.comments(number) })
+          json(res, 200, { task, comments: store.comments(key) })
           return
         }
         if (req.method === "PATCH") {
           void readBody(req)
             .then((body) => {
-              const task = store.update(number, parsePatch(body))
+              const task = store.update(key, parsePatch(body))
               json(res, 200, { task })
             })
             .catch((error: Error) => json(res, 400, { error: error.message }))
           return
         }
         if (req.method === "DELETE") {
-          store.delete(number)
+          store.delete(key)
           json(res, 200, { ok: true })
           return
         }

package/src/store.test.ts

@@ -14,7 +14,8 @@ import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "nod
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { FileStore, initProject, openBoard } from "./file-store.ts"
-import { parseTicket, serializeTicket, type TicketDoc } from "./ticket-doc.ts"
+import { KEY_PATTERN } from "./id.ts"
+import { parseTicket, parseTicketLenient, serializeTicket, type TicketDoc } from "./ticket-doc.ts"
 import { findBoardsByPrefix, findScopeRoot } from "./store.ts"
 
 function tempRoot(): string {
@@ -31,7 +32,6 @@ test("ticket documents round-trip, including the awkward bodies", () => {
       status: "todo",
       tags: [],
       goal: null,
-      needsHuman: false,
       blockedBy: [],
       prs: [],
       position: 1024,
@@ -46,8 +46,7 @@ test("ticket documents round-trip, including the awkward bodies", () => {
       status: "in_progress",
       tags: ["storage", "architecture"],
       goal: "v2-storage",
-      needsHuman: true,
-      blockedBy: [3, 7],
+      blockedBy: ["k3mfp", "x7c2d"],
       prs: ["https://github.com/x/y/pull/1"],
       position: -512.5,
       createdAt: "2026-08-15T16:00:33.758Z",
@@ -59,7 +58,6 @@ test("ticket documents round-trip, including the awkward bodies", () => {
       status: "backlog",
       tags: [],
       goal: null,
-      needsHuman: false,
       blockedBy: [],
       prs: [],
       position: 0,
@@ -90,12 +88,15 @@ test("hand-edits are forgiven where they're unambiguous", () => {
   assert.equal(doc.goal, "launch")
   assert.equal(doc.position, 8)
 
-  // The pre-0.8 spelling still reads as the goal — old boards keep rendering,
-  // and `task check --fix`'s canonical rewrite is the migration.
-  const legacy = parseTicket(text.replace("goal: launch", "milestone: launch"), "test")
-  assert.equal(legacy.goal, "launch")
-  assert.match(serializeTicket(legacy), /goal: "launch"/)
-  assert.doesNotMatch(serializeTicket(legacy), /milestone/)
+  // The pre-0.8 `milestone:` spelling is refused by name (TAS-41: no compat)
+  // — reading past it would silently drop the goal, so the error carries the
+  // one edit that fixes the file. The lenient parser just ignores it.
+  assert.throws(
+    () => parseTicket(text.replace("goal: launch", "milestone: launch"), "test"),
+    /`milestone:` is the pre-0\.8 spelling.*rename the key to `goal:`/,
+  )
+  const degraded = parseTicketLenient(text.replace("goal: launch", "milestone: launch"))
+  assert.equal(degraded?.goal, null)
 
   assert.throws(
     () => parseTicket(text.replace("status: todo", "status: todoo"), "here"),
@@ -113,50 +114,61 @@ test("FileStore keeps the store's contract", () => {
   const a = store.create({ title: "First", description: "alpha", tags: ["api"], status: "todo" })
   const b = store.create({ title: "Second", status: "todo" })
   const c = store.create({ title: "Third", status: "backlog" })
-  assert.deepEqual([a.number, b.number, c.number], [1, 2, 3])
+  // Keys are random, well-formed, and distinct — never sequential (TAS-42).
+  for (const t of [a, b, c]) assert.match(t.key, KEY_PATTERN)
+  assert.equal(new Set([a.key, b.key, c.key]).size, 3)
+  assert.equal(a.id, `SAM-${a.key}`)
   // New tasks land at the bottom of their column.
   assert.ok(b.position > a.position)
 
   // Status move without an explicit slot lands on top of the new column.
-  const moved = store.update(c.number, { status: "todo" })
+  const moved = store.update(c.key, { status: "todo" })
   assert.ok(moved.position < a.position)
-  assert.equal(store.list({ statuses: ["todo"] })[0].number, c.number)
+  assert.equal(store.list({ statuses: ["todo"] })[0].key, c.key)
 
   // One relation, two views, stored on one side only.
-  store.link(a.number, "blocked_by", b.number)
-  assert.deepEqual(store.get(b.number)!.blocks, [a.number])
-  const onDisk = readFileSync(join(root, ".task", "tickets", "1", "ticket.md"), "utf8")
-  assert.match(onDisk, /blocked_by: \[2\]/)
+  store.link(a.key, "blocked_by", b.key)
+  assert.deepEqual(store.get(b.key)!.blocks, [a.key])
+  const onDisk = readFileSync(join(root, ".task", "tickets", a.key, "ticket.md"), "utf8")
+  assert.ok(onDisk.includes(`blocked_by: ["${b.key}"]`))
   assert.doesNotMatch(
-    readFileSync(join(root, ".task", "tickets", "2", "ticket.md"), "utf8"),
+    readFileSync(join(root, ".task", "tickets", b.key, "ticket.md"), "utf8"),
     /blocked_by/,
   )
-  store.unlink(b.number, "blocks", a.number)
-  assert.deepEqual(store.get(a.number)!.blockedBy, [])
-
-  assert.throws(() => store.link(a.number, "blocks", a.number), /can't block itself/)
-  assert.throws(() => store.update(a.number, { blockedBy: [99] }), /no such task: SAM-99/)
+  store.unlink(b.key, "blocks", a.key)
+  assert.deepEqual(store.get(a.key)!.blockedBy, [])
+
+  assert.throws(() => store.link(a.key, "blocks", a.key), /can't block itself/)
+  assert.throws(() => store.update(a.key, { blockedBy: ["zz9zz"] }), /no such task: SAM-zz9zz/)
+
+  // parseId: exact keys, PREFIX-key, and unique git-style prefixes all land.
+  assert.equal(store.parseId(a.key), a.key)
+  assert.equal(store.parseId(`SAM-${a.key}`), a.key)
+  assert.equal(store.parseId(a.key.toUpperCase()), a.key)
+  const uniquePrefix = [a, b, c].every((t) => t.key[0] !== a.key[0] || t.key === a.key)
+    ? a.key[0]
+    : a.key.slice(0, 4)
+  if ([a, b, c].filter((t) => t.key.startsWith(uniquePrefix)).length === 1) {
+    assert.equal(store.parseId(uniquePrefix), a.key)
+  }
+  assert.throws(() => store.parseId("not an id!"), /invalid task id/)
 
   // Comments: one file each, stable ids, author preserved.
-  const comment = store.addComment(a.number, "first!\n\nwith **markdown**", "claude")
+  const comment = store.addComment(a.key, "first!\n\nwith **markdown**", "claude")
   assert.match(comment.id, /^\d{4}-\d{2}-\d{2}T\d{6}-claude$/)
-  assert.equal(store.comments(a.number)[0].body, "first!\n\nwith **markdown**")
-  assert.equal(store.commentCounts().get(a.number), 1)
-  const second = store.addComment(a.number, "again", "claude")
+  assert.equal(store.comments(a.key)[0].body, "first!\n\nwith **markdown**")
+  assert.equal(store.commentCounts().get(a.key), 1)
+  const second = store.addComment(a.key, "again", "claude")
   assert.notEqual(second.id, comment.id)
-  store.deleteComment(a.number, second.id)
-  assert.equal(store.comments(a.number).length, 1)
-  assert.throws(() => store.deleteComment(a.number, "../../escape"), /no such comment/)
+  store.deleteComment(a.key, second.id)
+  assert.equal(store.comments(a.key).length, 1)
+  assert.throws(() => store.deleteComment(a.key, "../../escape"), /no such comment/)
 
   // Delete cascades the relation away, like the FK did.
-  store.link(b.number, "blocked_by", a.number)
-  store.delete(a.number)
-  assert.equal(store.get(a.number), null)
-  assert.deepEqual(store.get(b.number)!.blockedBy, [])
-
-  // Numbers never move backwards past an existing ticket.
-  const d = store.create({ title: "Fourth" })
-  assert.equal(d.number, 4)
+  store.link(b.key, "blocked_by", a.key)
+  store.delete(a.key)
+  assert.equal(store.get(a.key), null)
+  assert.deepEqual(store.get(b.key)!.blockedBy, [])
 })
 
 test("openBoard reads text boards, and refuses a pre-0.6 SQLite board loudly", () => {
@@ -192,45 +204,48 @@ test("archive moves finished tickets off the hot path, losing nothing", () => {
   const store = initProject(root, { name: "archive test", prefix: "ARC" })
   const keep = store.create({ title: "Still open", status: "todo" })
   const old = store.create({ title: "Finished work", status: "todo" })
-  store.link(keep.number, "blocked_by", old.number)
-  store.addComment(old.number, "how it went", "nick")
+  store.link(keep.key, "blocked_by", old.key)
+  store.addComment(old.key, "how it went", "nick")
 
   // Only finished work qualifies — archive is history, not a hiding place.
-  assert.throws(() => store.archive(old.number), /is todo/)
-  store.update(old.number, { status: "done" })
-  const archived = store.archive(old.number)
+  assert.throws(() => store.archive(old.key), /is todo/)
+  store.update(old.key, { status: "done" })
+  const archived = store.archive(old.key)
   assert.equal(archived.archived, true)
 
   // Off the board and out of every default read…
-  assert.deepEqual(store.list({}).map((t) => t.number), [keep.number])
-  assert.equal(store.commentCounts().get(old.number), undefined)
+  assert.deepEqual(store.list({}).map((t) => t.key), [keep.key])
+  assert.equal(store.commentCounts().get(old.key), undefined)
   // …but reads still reach it, comments included, and its links still show.
-  const shown = store.get(old.number)!
+  const shown = store.get(old.key)!
   assert.equal(shown.archived, true)
-  assert.deepEqual(shown.blocks, [keep.number])
-  assert.equal(store.comments(old.number)[0].body, "how it went")
+  assert.deepEqual(shown.blocks, [keep.key])
+  assert.equal(store.comments(old.key)[0].body, "how it went")
   const listed = store.list({ archived: true })
-  assert.deepEqual(listed.map((t) => [t.number, t.archived]), [[old.number, true]])
+  assert.deepEqual(listed.map((t) => [t.key, t.archived]), [[old.key, true]])
 
   // Writes refuse until unarchived, with a message that says what to do.
-  assert.throws(() => store.update(old.number, { title: "x" }), /archived — run/)
-  assert.throws(() => store.addComment(old.number, "x", "y"), /archived — run/)
-  assert.throws(() => store.delete(old.number), /archived — run/)
-  assert.throws(() => store.archive(old.number), /already archived/)
+  assert.throws(() => store.update(old.key, { title: "x" }), /archived — run/)
+  assert.throws(() => store.addComment(old.key, "x", "y"), /archived — run/)
+  assert.throws(() => store.delete(old.key), /archived — run/)
+  assert.throws(() => store.archive(old.key), /already archived/)
   // Linking *to* an archived target refuses; pruning a stale link succeeds.
-  assert.throws(() => store.link(keep.number, "blocked_by", old.number), /archived — run/)
-  assert.deepEqual(store.update(keep.number, { blockedBy: [] }).blockedBy, [])
+  assert.throws(() => store.link(keep.key, "blocked_by", old.key), /archived — run/)
+  assert.deepEqual(store.update(keep.key, { blockedBy: [] }).blockedBy, [])
 
-  // Numbers stay reserved — the next ticket never reuses an archived one.
-  assert.equal(store.create({ title: "Next" }).number, 3)
+  // Keys stay reserved — a new mint can never take an archived ticket's name.
+  const next = store.create({ title: "Next" })
+  assert.notEqual(next.key, old.key)
+  // An archived key still resolves through parseId (exact match).
+  assert.equal(store.parseId(`ARC-${old.key}`), old.key)
 
   // Round trip: unarchive puts it back exactly as it was.
-  const back = store.unarchive(old.number)
+  const back = store.unarchive(old.key)
   assert.equal(back.archived, undefined)
   assert.equal(back.status, "done")
   assert.deepEqual(store.list({ archived: true }), [])
-  assert.equal(store.comments(old.number).length, 1)
-  assert.throws(() => store.unarchive(old.number), /isn't archived/)
+  assert.equal(store.comments(old.key).length, 1)
+  assert.throws(() => store.unarchive(old.key), /isn't archived/)
 })
 
 test("goals: titled and described, one per task, progress always derived", () => {
@@ -251,13 +266,13 @@ test("goals: titled and described, one per task, progress always derived", () =>
   assert.throws(() => store.create({ title: "T", goal: "nope" }), /no such goal/)
   const a = store.create({ title: "First", goal: goal.slug })
   const b = store.create({ title: "Second" })
-  store.update(b.number, { goal: goal.slug })
-  assert.equal(store.get(b.number)!.goal, goal.slug)
-  assert.deepEqual(store.list({ goal: goal.slug }).map((t) => t.number), [a.number, b.number])
+  store.update(b.key, { goal: goal.slug })
+  assert.equal(store.get(b.key)!.goal, goal.slug)
+  assert.deepEqual(store.list({ goal: goal.slug }).map((t) => t.key), [a.key, b.key])
 
   // The file is the state: goal ref serialized on the ticket, goal file on disk.
   assert.match(
-    readFileSync(join(root, ".task", "tickets", "1", "ticket.md"), "utf8"),
+    readFileSync(join(root, ".task", "tickets", a.key, "ticket.md"), "utf8"),
     /goal: "trust-guardrail-layer"/,
   )
   const goalFile = readFileSync(join(root, ".task", "goals", "trust-guardrail-layer.md"), "utf8")
@@ -266,26 +281,29 @@ test("goals: titled and described, one per task, progress always derived", () =>
   // Update touches the file; clearing a task's goal is `goal: null`.
   store.updateGoal(goal.slug, { description: "Sharper why." })
   assert.equal(store.getGoal(goal.slug)!.description, "Sharper why.")
-  store.update(b.number, { goal: null })
-  assert.equal(store.get(b.number)!.goal, null)
+  store.update(b.key, { goal: null })
+  assert.equal(store.get(b.key)!.goal, null)
 
   // Archive refuses while open work references the goal, allows after.
-  assert.throws(() => store.archiveGoal(goal.slug), /still has open tasks \(GOA-1\)/)
-  store.update(a.number, { status: "done" })
+  assert.throws(
+    () => store.archiveGoal(goal.slug),
+    new RegExp(`still has open tasks \\(GOA-${a.key}\\)`),
+  )
+  store.update(a.key, { status: "done" })
   const shelved = store.archiveGoal(goal.slug)
   assert.equal(shelved.archived, true)
   assert.deepEqual(store.goals().map((g) => g.slug), [])
   assert.deepEqual(store.goals(true).map((g) => g.slug), [goal.slug])
   // Still resolvable (done tickets keep their ref readable), not assignable.
   assert.equal(store.getGoal(goal.slug)!.title, "Trust & guardrail layer")
-  assert.throws(() => store.update(b.number, { goal: goal.slug }), /is archived — run/)
+  assert.throws(() => store.update(b.key, { goal: goal.slug }), /is archived — run/)
   assert.throws(() => store.updateGoal(goal.slug, { title: "x" }), /is archived — run/)
 
   // Delete needs every live ref cleared first — pruning organization is a
   // human call, so the human makes it.
   store.unarchiveGoal(goal.slug)
-  assert.throws(() => store.deleteGoal(goal.slug), /referenced by GOA-1/)
-  store.update(a.number, { goal: null })
+  assert.throws(() => store.deleteGoal(goal.slug), new RegExp(`referenced by GOA-${a.key}`))
+  store.update(a.key, { goal: null })
   store.deleteGoal(goal.slug)
   assert.equal(store.getGoal(goal.slug), null)
 })
@@ -312,22 +330,22 @@ test("concurrent-writer shapes merge by construction", () => {
 
   // Two agents commenting at once = two files; simulate the second writer by
   // dropping its file in directly, the way a git merge would.
-  store.addComment(task.number, "from session one", "claude")
-  const commentsDir = join(root, ".task", "tickets", String(task.number), "comments")
+  store.addComment(task.key, "from session one", "claude")
+  const commentsDir = join(root, ".task", "tickets", task.key, "comments")
   writeFileSync(
     join(commentsDir, "2026-08-15T170000-other.md"),
     "---\nauthor: \"other\"\ncreated: 2026-08-15T17:00:00.000Z\n---\n\nfrom session two\n",
   )
-  assert.equal(store.comments(task.number).length, 2)
+  assert.equal(store.comments(task.key).length, 2)
 
   // A claim is a one-line diff: exactly one meaningful frontmatter line
   // changes. `updated:` is excluded because it only changes when the update
   // lands in a different millisecond than the create — true except when this
   // test runs fast enough, which is exactly the kind of coin-flip a test must
   // not depend on.
-  const path = join(root, ".task", "tickets", String(task.number), "ticket.md")
+  const path = join(root, ".task", "tickets", task.key, "ticket.md")
   const before = readFileSync(path, "utf8").split("\n")
-  store.update(task.number, { status: "in_progress", position: task.position })
+  store.update(task.key, { status: "in_progress", position: task.position })
   const after = readFileSync(path, "utf8").split("\n")
   const changed = before.filter((line, i) => after[i] !== line)
   assert.deepEqual(