@nickmeriano/task 0.8.0 → 0.9.0

package/src/file-store.ts

@@ -11,16 +11,20 @@ import { basename, dirname, join } from "node:path"
 import {
   commentStem,
   isGoalSlug,
+  parseAsk,
   parseComment,
   parseGoal,
   parseTicket,
+  serializeAsk,
   serializeComment,
   serializeGoal,
   serializeTicket,
   slugifyGoal,
+  type AskDoc,
   type GoalDoc,
   type TicketDoc,
 } from "./ticket-doc.ts"
+import { isTicketKey, mintKey } from "./id.ts"
 import {
   CONFIG_FILE,
   POSITION_GAP,
@@ -29,6 +33,7 @@ import {
   type Store,
 } from "./store.ts"
 import type {
+  Ask,
   Comment,
   Goal,
   GoalInput,
@@ -46,6 +51,8 @@ export const TICKETS_DIR = "tickets"
 export const ARCHIVE_DIR = "archive"
 export const TICKET_FILE = "ticket.md"
 export const COMMENTS_DIR = "comments"
+/** One file per ask — `tickets/<key>/asks/<stem>.md`, the comment layout. */
+export const ASKS_DIR = "asks"
 /** One file per goal — `.task/goals/<slug>.md`; archived ones one level down. */
 export const GOALS_DIR = "goals"
 export const GOALS_ARCHIVE_DIR = "archive"
@@ -65,17 +72,28 @@ function writeAtomic(path: string, text: string): void {
 }
 
 interface Ticket {
-  number: number
+  key: string
   doc: TicketDoc
 }
 
+/** Stable sort for key lists — lexicographic, since keys carry no order. */
+function sortKeys(keys: string[]): string[] {
+  return keys.sort((a, b) => a.localeCompare(b))
+}
+
+/** Board order's tiebreak: creation time, then key — keys themselves say nothing. */
+function byCreation(a: Ticket, b: Ticket): number {
+  return a.doc.createdAt.localeCompare(b.doc.createdAt) || a.key.localeCompare(b.key)
+}
+
 /**
  * The canonical persistence layer: one directory per ticket under
- * `.task/tickets/`, holding a frontmatter+markdown `ticket.md` and one file
- * per comment. Everything is plain text committed to git, which is the point —
- * ticket edits diff, review, and merge like code, and two branches touching
- * different tickets (or adding comments to the same one) merge cleanly by
- * construction.
+ * `.task/tickets/`, named by the ticket's key (see id.ts), holding a
+ * frontmatter+markdown `ticket.md` and one file per comment. Everything is
+ * plain text committed to git, which is the point — ticket edits diff, review,
+ * and merge like code, and two branches creating tickets (or adding comments
+ * to the same one) merge cleanly by construction: keys are random, so parallel
+ * branches can't mint the same directory.
  *
  * There is no database and no cache: boards are dozens of tickets, and
  * re-reading a handful of small files per operation is cheaper than opening
@@ -105,44 +123,57 @@ export class FileStore implements Store {
 
   close(): void {}
 
-  displayId(number: number): string {
-    return `${this.config.prefix}-${number}`
+  displayId(key: string): string {
+    return `${this.config.prefix}-${key}`
   }
 
-  /** Accepts "PHONE-12", "phone-12" or "12". */
-  parseId(ref: string): number {
-    const match = /^(?:[A-Za-z0-9]+-)?(\d+)$/.exec(ref.trim())
+  /**
+   * "PHO-x7k4m", "x7k4m", or any unique prefix of a key ("x7") — resolved
+   * git-style against the board's live and archived tickets, case-insensitive.
+   * An ambiguous prefix throws naming the candidates; an unknown ref comes
+   * back verbatim, so the caller's lookup says "no such task" with it.
+   */
+  parseId(ref: string): string {
+    const match = /^(?:[A-Za-z0-9]+-)?([A-Za-z0-9]+)$/.exec(ref.trim())
     if (!match) throw new Error(`invalid task id: ${ref}`)
-    return Number(match[1])
+    const key = match[1].toLowerCase()
+    const known = [...this.liveKeys(), ...this.archivedKeys()]
+    if (known.includes(key)) return key
+    const hits = sortKeys(known.filter((k) => k.startsWith(key)))
+    if (hits.length === 1) return hits[0]
+    if (hits.length > 1) {
+      throw new Error(
+        `${ref} is ambiguous — matches ${hits.map((k) => this.displayId(k)).join(", ")}`,
+      )
+    }
+    return key
   }
 
   // ── Reading ────────────────────────────────────────────────────────────────
 
-  private ticketPath(number: number): string {
-    return join(this.ticketsDir, String(number), TICKET_FILE)
+  private ticketPath(key: string): string {
+    return join(this.ticketsDir, key, TICKET_FILE)
   }
 
   /**
    * A ticket's comments live wherever the ticket does — the whole directory
    * moves on archive, so an archived ticket's discussion stays readable.
    */
-  private commentsPath(number: number): string {
-    const home = existsSync(join(this.archiveDir, String(number)))
-      ? this.archiveDir
-      : this.ticketsDir
-    return join(home, String(number), COMMENTS_DIR)
+  private commentsPath(key: string): string {
+    const home = existsSync(join(this.archiveDir, key)) ? this.archiveDir : this.ticketsDir
+    return join(home, key, COMMENTS_DIR)
   }
 
   private readDir(dir: string): Ticket[] {
     if (!existsSync(dir)) return []
     const tickets: Ticket[] = []
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      if (!entry.isDirectory() || !/^\d+$/.test(entry.name)) continue
+      if (!entry.isDirectory() || !isTicketKey(entry.name)) continue
       const path = join(dir, entry.name, TICKET_FILE)
       if (!existsSync(path)) continue
-      tickets.push({ number: Number(entry.name), doc: parseTicket(readFileSync(path, "utf8"), path) })
+      tickets.push({ key: entry.name, doc: parseTicket(readFileSync(path, "utf8"), path) })
     }
-    tickets.sort((a, b) => a.number - b.number)
+    tickets.sort(byCreation)
     return tickets
   }
 
@@ -151,56 +182,66 @@ export class FileStore implements Store {
     return this.readDir(this.ticketsDir)
   }
 
-  private readOne(number: number): Ticket | null {
-    const path = this.ticketPath(number)
-    if (!existsSync(path)) return null
-    return { number, doc: parseTicket(readFileSync(path, "utf8"), path) }
+  private readOne(key: string): Ticket | null {
+    const path = this.ticketPath(key)
+    if (!isTicketKey(key) || !existsSync(path)) return null
+    return { key, doc: parseTicket(readFileSync(path, "utf8"), path) }
   }
 
-  /** Cheap presence check — the archive's numbers, without parsing anything. */
-  private archivedNumbers(): number[] {
-    if (!existsSync(this.archiveDir)) return []
-    return readdirSync(this.archiveDir)
-      .filter((name) => /^\d+$/.test(name))
-      .map(Number)
+  /** Directory names that are well-formed keys, without parsing anything. */
+  private keysIn(dir: string): string[] {
+    if (!existsSync(dir)) return []
+    return readdirSync(dir).filter(isTicketKey)
   }
 
-  private isArchived(number: number): boolean {
-    return existsSync(join(this.archiveDir, String(number), TICKET_FILE))
+  private liveKeys(): string[] {
+    return this.keysIn(this.ticketsDir)
+  }
+
+  /** Cheap presence check — the archive's keys, without parsing anything. */
+  private archivedKeys(): string[] {
+    return this.keysIn(this.archiveDir)
+  }
+
+  private isArchived(key: string): boolean {
+    return isTicketKey(key) && existsSync(join(this.archiveDir, key, TICKET_FILE))
   }
 
   /** The error every write path throws instead of touching the archive. */
-  private assertNotArchived(number: number): void {
-    if (this.isArchived(number)) {
-      const id = this.displayId(number)
+  private assertNotArchived(key: string): void {
+    if (this.isArchived(key)) {
+      const id = this.displayId(key)
       throw new Error(`${id} is archived — run \`task unarchive ${id}\` first`)
     }
   }
 
   private writeTicket(ticket: Ticket): void {
-    mkdirSync(dirname(this.ticketPath(ticket.number)), { recursive: true })
-    writeAtomic(this.ticketPath(ticket.number), serializeTicket(ticket.doc))
+    mkdirSync(dirname(this.ticketPath(ticket.key)), { recursive: true })
+    writeAtomic(this.ticketPath(ticket.key), serializeTicket(ticket.doc))
   }
 
   /**
    * Only `blocked_by` is stored (on the blocked ticket); the `blocks` side is
-   * derived here, so the two views can never disagree.
+   * derived here, so the two views can never disagree. `needsHuman` is derived
+   * too — open asks, nothing else — so a flagged ticket with no stated reason
+   * cannot exist.
    */
-  private toTask(ticket: Ticket, all: Ticket[]): Task {
-    const blocks = all
-      .filter((t) => t.doc.blockedBy.includes(ticket.number))
-      .map((t) => t.number)
+  private toTask(ticket: Ticket, all: Ticket[], asks: Ask[] = this.asks(ticket.key)): Task {
+    const blocks = sortKeys(
+      all.filter((t) => t.doc.blockedBy.includes(ticket.key)).map((t) => t.key),
+    )
     return {
-      id: this.displayId(ticket.number),
-      number: ticket.number,
+      id: this.displayId(ticket.key),
+      key: ticket.key,
       title: ticket.doc.title,
       description: ticket.doc.description,
       status: ticket.doc.status,
       tags: ticket.doc.tags,
       goal: ticket.doc.goal,
-      needsHuman: ticket.doc.needsHuman,
+      needsHuman: asks.some((a) => !a.resolvedAt),
+      asks,
       blocks,
-      blockedBy: [...ticket.doc.blockedBy].sort((a, b) => a - b),
+      blockedBy: sortKeys([...ticket.doc.blockedBy]),
       prs: ticket.doc.prs,
       position: ticket.doc.position,
       createdAt: ticket.doc.createdAt,
@@ -217,7 +258,11 @@ export class FileStore implements Store {
       tickets = tickets.filter((t) => t.doc.goal === filter.goal)
     }
     if (filter.needsHuman !== undefined) {
-      tickets = tickets.filter((t) => t.doc.needsHuman === filter.needsHuman)
+      // The derived flag, same definition as toTask — filtering must never
+      // disagree with what the payload says.
+      tickets = tickets.filter(
+        (t) => this.asks(t.key).some((a) => !a.resolvedAt) === filter.needsHuman,
+      )
     }
     if (filter.tags?.length) {
       const wanted = new Set(filter.tags)
@@ -235,22 +280,23 @@ export class FileStore implements Store {
       const everything = [...this.readAll(), ...archived]
       return this.applyFilter(archived, filter)
         .map((t) => ({ ...this.toTask(t, everything), archived: true }))
-        .sort((a, b) => a.position - b.position || a.number - b.number)
+        .sort((a, b) => a.position - b.position || byCreationTask(a, b))
     }
     const all = this.readAll()
     return this.applyFilter(all, filter)
       .map((t) => this.toTask(t, all))
-      .sort((a, b) => a.position - b.position || a.number - b.number)
+      .sort((a, b) => a.position - b.position || byCreationTask(a, b))
   }
 
-  get(number: number): Task | null {
+  get(key: string): Task | null {
     const all = this.readAll()
-    const ticket = all.find((t) => t.number === number)
+    const ticket = all.find((t) => t.key === key)
     if (ticket) return this.toTask(ticket, all)
     // `show` should reach the archive without ceremony — reads are safe.
-    const path = join(this.archiveDir, String(number), TICKET_FILE)
+    if (!isTicketKey(key)) return null
+    const path = join(this.archiveDir, key, TICKET_FILE)
     if (!existsSync(path)) return null
-    const archived: Ticket = { number, doc: parseTicket(readFileSync(path, "utf8"), path) }
+    const archived: Ticket = { key, doc: parseTicket(readFileSync(path, "utf8"), path) }
     return { ...this.toTask(archived, [...all, archived]), archived: true }
   }
 
@@ -258,15 +304,16 @@ export class FileStore implements Store {
 
   create(input: TaskInput): Task {
     const all = this.readAll()
-    // Archived numbers stay reserved — a new ticket must never take a number
-    // that old comments or PR titles still point at.
-    const taken = [...all.map((t) => t.number), ...this.archivedNumbers()]
-    const number = taken.reduce((max, n) => Math.max(max, n), 0) + 1
+    // Random, not sequential (TAS-42): the key must be safe to mint on any
+    // branch with no coordination. Archived keys stay reserved — a new ticket
+    // must never take a name old comments or PR titles still point at.
+    const taken = new Set([...all.map((t) => t.key), ...this.archivedKeys()])
+    const key = mintKey(taken)
     // Dump by default: new tickets land in backlog, the no-quality-bar list;
     // `todo` (the ready list) is an explicit choice — usually `task promote`.
     const status = input.status ?? "backlog"
     for (const target of [...(input.blocks ?? []), ...(input.blockedBy ?? [])]) {
-      if (!all.some((t) => t.number === target)) {
+      if (!all.some((t) => t.key === target)) {
         throw new Error(`no such task: ${this.displayId(target)}`)
       }
     }
@@ -276,15 +323,14 @@ export class FileStore implements Store {
     const bottom = column.length ? Math.max(...column.map((t) => t.doc.position)) : 0
     const timestamp = now()
     const ticket: Ticket = {
-      number,
+      key,
       doc: {
         title: input.title,
         description: input.description ?? "",
         status,
         tags: input.tags ?? [],
         goal: input.goal ?? null,
-        needsHuman: input.needsHuman ?? false,
-        blockedBy: [...new Set(input.blockedBy ?? [])].sort((a, b) => a - b),
+        blockedBy: sortKeys([...new Set(input.blockedBy ?? [])]),
         prs: input.prs ?? [],
         position: bottom + POSITION_GAP,
         createdAt: timestamp,
@@ -293,27 +339,27 @@ export class FileStore implements Store {
     }
     this.writeTicket(ticket)
     if (input.blocks !== undefined) {
-      this.reconcileBlocks(number, [...all, ticket], input.blocks, timestamp)
+      this.reconcileBlocks(key, [...all, ticket], input.blocks, timestamp)
     }
-    return this.get(number)!
+    return this.get(key)!
   }
 
-  update(number: number, patch: TaskPatch): Task {
+  update(key: string, patch: TaskPatch): Task {
     const all = this.readAll()
-    const ticket = all.find((t) => t.number === number)
+    const ticket = all.find((t) => t.key === key)
     if (!ticket) {
-      this.assertNotArchived(number)
-      throw new Error(`no such task: ${this.displayId(number)}`)
+      this.assertNotArchived(key)
+      throw new Error(`no such task: ${this.displayId(key)}`)
     }
 
     // Validate link targets before any file is written, so a bad target
     // rejects the whole patch — the transactional behavior the SQLite store
     // got for free.
     for (const target of [...(patch.blocks ?? []), ...(patch.blockedBy ?? [])]) {
-      if (target === number) {
-        throw new Error(`a task can't block itself: ${this.displayId(number)}`)
+      if (target === key) {
+        throw new Error(`a task can't block itself: ${this.displayId(key)}`)
       }
-      if (!all.some((t) => t.number === target)) {
+      if (!all.some((t) => t.key === target)) {
         this.assertNotArchived(target)
         throw new Error(`no such task: ${this.displayId(target)}`)
       }
@@ -322,14 +368,14 @@ export class FileStore implements Store {
     const timestamp = now()
     let linksChanged = false
     if (patch.blocks !== undefined) {
-      linksChanged = this.reconcileBlocks(number, all, patch.blocks, timestamp)
+      linksChanged = this.reconcileBlocks(key, all, patch.blocks, timestamp)
     }
     if (patch.blockedBy !== undefined) {
-      const wanted = [...new Set(patch.blockedBy)].sort((a, b) => a - b)
+      const wanted = sortKeys([...new Set(patch.blockedBy)])
       const current = ticket.doc.blockedBy
       const touched = [
-        ...current.filter((n) => !wanted.includes(n)),
-        ...wanted.filter((n) => !current.includes(n)),
+        ...current.filter((k) => !wanted.includes(k)),
+        ...wanted.filter((k) => !current.includes(k)),
       ]
       if (touched.length > 0) {
         linksChanged = true
@@ -337,8 +383,8 @@ export class FileStore implements Store {
         // The other end of every added or removed link gets its `updated`
         // bumped too — its derived `blocks` view just changed. A dangling
         // reference (hand-edit pointing at a deleted ticket) has no other end.
-        for (const n of touched) {
-          const other = all.find((t) => t.number === n)
+        for (const k of touched) {
+          const other = all.find((t) => t.key === k)
           if (!other) continue
           other.doc.updatedAt = timestamp
           this.writeTicket(other)
@@ -348,8 +394,8 @@ export class FileStore implements Store {
 
     const doc = ticket.doc
     let fieldsChanged = false
-    const set = <K extends keyof TicketDoc>(key: K, value: TicketDoc[K]) => {
-      doc[key] = value
+    const set = <K extends keyof TicketDoc>(field: K, value: TicketDoc[K]) => {
+      doc[field] = value
       fieldsChanged = true
     }
 
@@ -360,15 +406,28 @@ export class FileStore implements Store {
       if (patch.goal) this.assertGoalAssignable(patch.goal)
       set("goal", patch.goal)
     }
-    if (patch.needsHuman !== undefined) set("needsHuman", patch.needsHuman)
     if (patch.prs !== undefined) set("prs", patch.prs)
     if (patch.status !== undefined) {
+      // Done is gated on nothing owed: open asks refuse the move. Canceled
+      // stays open — a dead ticket's asks die with it and leave the inbox on
+      // their own.
+      if (patch.status === "done" && doc.status !== "done") {
+        const open = this.asks(key).filter((a) => !a.resolvedAt)
+        if (open.length > 0) {
+          const id = this.displayId(key)
+          throw new Error(
+            `${id} still has ${open.length} open ask${open.length === 1 ? "" : "s"} — done means nobody owes anything. ` +
+              `Resolve them (\`task resolve ${id} <n>\`) or move what's still owed to a new ticket:\n` +
+              open.map((a) => `  [${a.ordinal}] ${a.text.split("\n")[0]}`).join("\n"),
+          )
+        }
+      }
       const previous = doc.status
       set("status", patch.status)
       if (patch.position === undefined && patch.status !== previous) {
         // Moved columns without an explicit slot → land on top, where the
         // freshest movement is visible (Linear's behavior).
-        const column = all.filter((t) => t.number !== number && t.doc.status === patch.status)
+        const column = all.filter((t) => t.key !== key && t.doc.status === patch.status)
         const top = column.length ? Math.min(...column.map((t) => t.doc.position)) : 0
         set("position", top - POSITION_GAP)
       }
@@ -378,7 +437,7 @@ export class FileStore implements Store {
     if (!fieldsChanged && !linksChanged) return this.toTask(ticket, all)
     if (fieldsChanged || linksChanged) doc.updatedAt = timestamp
     this.writeTicket(ticket)
-    return this.get(number)!
+    return this.get(key)!
   }
 
   /**
@@ -387,30 +446,30 @@ export class FileStore implements Store {
    * (and, via the caller, this one) gets its `updated` bumped.
    */
   private reconcileBlocks(
-    number: number,
+    key: string,
     all: Ticket[],
-    targets: number[],
+    targets: string[],
     timestamp: string,
   ): boolean {
     const wanted = new Set(targets)
-    if (wanted.has(number)) {
-      throw new Error(`a task can't block itself: ${this.displayId(number)}`)
+    if (wanted.has(key)) {
+      throw new Error(`a task can't block itself: ${this.displayId(key)}`)
     }
     let changed = false
     for (const other of all) {
-      if (other.number === number) continue
-      const has = other.doc.blockedBy.includes(number)
-      const should = wanted.has(other.number)
+      if (other.key === key) continue
+      const has = other.doc.blockedBy.includes(key)
+      const should = wanted.has(other.key)
       if (has === should) continue
       other.doc.blockedBy = should
-        ? [...other.doc.blockedBy, number].sort((a, b) => a - b)
-        : other.doc.blockedBy.filter((n) => n !== number)
+        ? sortKeys([...other.doc.blockedBy, key])
+        : other.doc.blockedBy.filter((k) => k !== key)
       other.doc.updatedAt = timestamp
       this.writeTicket(other)
       changed = true
     }
     if (changed) {
-      const self = all.find((t) => t.number === number)
+      const self = all.find((t) => t.key === key)
       if (self) {
         self.doc.updatedAt = timestamp
         this.writeTicket(self)
@@ -420,37 +479,37 @@ export class FileStore implements Store {
   }
 
   /** `task link A --blocks B` and friends — additive, unlike the patch form. */
-  link(number: number, relation: "blocks" | "blocked_by", target: number): Task {
-    const task = this.get(number)
-    if (!task) throw new Error(`no such task: ${this.displayId(number)}`)
+  link(key: string, relation: "blocks" | "blocked_by", target: string): Task {
+    const task = this.get(key)
+    if (!task) throw new Error(`no such task: ${this.displayId(key)}`)
     const current = relation === "blocks" ? task.blocks : task.blockedBy
     const patch: TaskPatch =
       relation === "blocks"
         ? { blocks: [...current, target] }
         : { blockedBy: [...current, target] }
-    return this.update(number, patch)
+    return this.update(key, patch)
   }
 
-  unlink(number: number, relation: "blocks" | "blocked_by", target: number): Task {
-    const task = this.get(number)
-    if (!task) throw new Error(`no such task: ${this.displayId(number)}`)
+  unlink(key: string, relation: "blocks" | "blocked_by", target: string): Task {
+    const task = this.get(key)
+    if (!task) throw new Error(`no such task: ${this.displayId(key)}`)
     const current = relation === "blocks" ? task.blocks : task.blockedBy
-    const kept = current.filter((n) => n !== target)
+    const kept = current.filter((k) => k !== target)
     const patch: TaskPatch = relation === "blocks" ? { blocks: kept } : { blockedBy: kept }
-    return this.update(number, patch)
+    return this.update(key, patch)
   }
 
-  delete(number: number): void {
-    if (!this.readOne(number)) {
-      this.assertNotArchived(number)
-      throw new Error(`no such task: ${this.displayId(number)}`)
+  delete(key: string): void {
+    if (!this.readOne(key)) {
+      this.assertNotArchived(key)
+      throw new Error(`no such task: ${this.displayId(key)}`)
     }
-    rmSync(join(this.ticketsDir, String(number)), { recursive: true })
+    rmSync(join(this.ticketsDir, key), { recursive: true })
     // Links pointing at the deleted ticket go with it — the same cascade the
     // relation table had, so quiet on the other tickets' `updated`.
     for (const other of this.readAll()) {
-      if (!other.doc.blockedBy.includes(number)) continue
-      other.doc.blockedBy = other.doc.blockedBy.filter((n) => n !== number)
+      if (!other.doc.blockedBy.includes(key)) continue
+      other.doc.blockedBy = other.doc.blockedBy.filter((k) => k !== key)
       this.writeTicket(other)
     }
   }
@@ -461,41 +520,41 @@ export class FileStore implements Store {
    * Move a finished ticket's whole directory to `.task/archive/` — one rename,
    * which git records as a move, so history follows the ticket. Archived
    * tickets leave every hot path (`list`, the board, link derivation) but stay
-   * readable via `get`/`comments` and keep their number reserved forever.
+   * readable via `get`/`comments` and keep their key reserved forever.
    * Links other tickets hold on this one are left in place: they're
    * dangling-tolerant everywhere, and unarchiving puts them back in force.
    */
-  archive(number: number): Task {
-    const ticket = this.readOne(number)
+  archive(key: string): Task {
+    const ticket = this.readOne(key)
     if (!ticket) {
-      if (this.isArchived(number)) {
-        throw new Error(`${this.displayId(number)} is already archived`)
+      if (this.isArchived(key)) {
+        throw new Error(`${this.displayId(key)} is already archived`)
       }
-      throw new Error(`no such task: ${this.displayId(number)}`)
+      throw new Error(`no such task: ${this.displayId(key)}`)
     }
     if (ticket.doc.status !== "done" && ticket.doc.status !== "canceled") {
       throw new Error(
-        `${this.displayId(number)} is ${ticket.doc.status} — only done or canceled tickets can be archived`,
+        `${this.displayId(key)} is ${ticket.doc.status} — only done or canceled tickets can be archived`,
       )
     }
     mkdirSync(this.archiveDir, { recursive: true })
-    renameSync(join(this.ticketsDir, String(number)), join(this.archiveDir, String(number)))
-    return this.get(number)!
+    renameSync(join(this.ticketsDir, key), join(this.archiveDir, key))
+    return this.get(key)!
   }
 
-  unarchive(number: number): Task {
-    if (!this.isArchived(number)) {
+  unarchive(key: string): Task {
+    if (!this.isArchived(key)) {
       throw new Error(
-        this.readOne(number)
-          ? `${this.displayId(number)} isn't archived`
-          : `no such task: ${this.displayId(number)}`,
+        this.readOne(key)
+          ? `${this.displayId(key)} isn't archived`
+          : `no such task: ${this.displayId(key)}`,
       )
     }
     // A checkout where everything is archived has no tickets/ at all — git
     // doesn't keep empty directories.
     mkdirSync(this.ticketsDir, { recursive: true })
-    renameSync(join(this.archiveDir, String(number)), join(this.ticketsDir, String(number)))
-    return this.get(number)!
+    renameSync(join(this.archiveDir, key), join(this.ticketsDir, key))
+    return this.get(key)!
   }
 
   // ── Goals ──────────────────────────────────────────────────────────────────
@@ -621,7 +680,7 @@ export class FileStore implements Store {
       (t) => t.doc.goal === slug && t.doc.status !== "done" && t.doc.status !== "canceled",
     )
     if (open.length > 0) {
-      const ids = open.map((t) => this.displayId(t.number)).join(", ")
+      const ids = open.map((t) => this.displayId(t.key)).join(", ")
       throw new Error(`goal "${slug}" still has open tasks (${ids}) — finish or reassign them first`)
     }
     mkdirSync(this.goalsArchiveDir, { recursive: true })
@@ -659,7 +718,7 @@ export class FileStore implements Store {
     }
     const referencing = this.readAll().filter((t) => t.doc.goal === slug)
     if (referencing.length > 0) {
-      const ids = referencing.map((t) => this.displayId(t.number)).join(", ")
+      const ids = referencing.map((t) => this.displayId(t.key)).join(", ")
       throw new Error(
         `goal "${slug}" is referenced by ${ids} — clear those with \`task update <id> --goal ""\` first`,
       )
@@ -674,8 +733,8 @@ export class FileStore implements Store {
    * the same ticket produce two files and merge without a conflict — which is
    * why they aren't lines inside `ticket.md`.
    */
-  comments(number: number): Comment[] {
-    const dir = this.commentsPath(number)
+  comments(key: string): Comment[] {
+    const dir = this.commentsPath(key)
     if (!existsSync(dir)) return []
     const comments: Comment[] = []
     for (const entry of readdirSync(dir)) {
@@ -684,7 +743,7 @@ export class FileStore implements Store {
       const doc = parseComment(readFileSync(path, "utf8"), path)
       comments.push({
         id: entry.slice(0, -3),
-        taskId: this.displayId(number),
+        taskId: this.displayId(key),
         author: doc.author,
         body: doc.body,
         createdAt: doc.createdAt,
@@ -696,45 +755,187 @@ export class FileStore implements Store {
     return comments
   }
 
-  addComment(number: number, body: string, author = ""): Comment {
-    if (!this.readOne(number)) {
-      this.assertNotArchived(number)
-      throw new Error(`no such task: ${this.displayId(number)}`)
+  addComment(key: string, body: string, author = ""): Comment {
+    if (!this.readOne(key)) {
+      this.assertNotArchived(key)
+      throw new Error(`no such task: ${this.displayId(key)}`)
     }
     const createdAt = now()
-    const dir = this.commentsPath(number)
+    const dir = this.commentsPath(key)
     mkdirSync(dir, { recursive: true })
     const stem = commentStem(createdAt, author)
     let id = stem
     for (let n = 2; existsSync(join(dir, `${id}.md`)); n++) id = `${stem}-${n}`
     writeAtomic(join(dir, `${id}.md`), serializeComment({ author, createdAt, body }))
-    return { id, taskId: this.displayId(number), author, body, createdAt }
+    return { id, taskId: this.displayId(key), author, body, createdAt }
   }
 
-  deleteComment(number: number, commentId: string): Comment {
+  deleteComment(key: string, commentId: string): Comment {
     // Resolve the id against the directory listing rather than building a path
     // from it — the id arrived over HTTP and must not be able to point
     // anywhere but at an actual comment of this task.
-    const existing = this.comments(number).find((c) => c.id === commentId)
+    const existing = this.comments(key).find((c) => c.id === commentId)
     if (!existing) {
-      throw new Error(`no such comment on ${this.displayId(number)}: ${commentId}`)
+      throw new Error(`no such comment on ${this.displayId(key)}: ${commentId}`)
     }
-    rmSync(join(this.commentsPath(number), `${commentId}.md`))
+    rmSync(join(this.commentsPath(key), `${commentId}.md`))
     return existing
   }
 
-  commentCounts(): Map<number, number> {
-    const counts = new Map<number, number>()
+  commentCounts(): Map<string, number> {
+    const counts = new Map<string, number>()
     for (const ticket of this.readAll()) {
-      const dir = this.commentsPath(ticket.number)
+      const dir = this.commentsPath(ticket.key)
       if (!existsSync(dir)) continue
       const count = readdirSync(dir).filter(
         (f) => f.endsWith(".md") && !f.startsWith("."),
       ).length
-      if (count > 0) counts.set(ticket.number, count)
+      if (count > 0) counts.set(ticket.key, count)
     }
     return counts
   }
+
+  // ── Asks ───────────────────────────────────────────────────────────────────
+
+  /** Like comments, an archived ticket keeps its asks readable in place. */
+  private asksPath(key: string): string {
+    const home = existsSync(join(this.archiveDir, key)) ? this.archiveDir : this.ticketsDir
+    return join(home, key, ASKS_DIR)
+  }
+
+  /**
+   * Every ask on a ticket, open and resolved, in creation order — the order
+   * that fixes each ask's ordinal, the short handle `task resolve` takes.
+   * Ordinals are positions in this listing rather than stored, so two branches
+   * adding asks concurrently can't mint a duplicate; they shift only if an ask
+   * is deleted outright, which is why resolving (not deleting) is the normal
+   * way an ask ends.
+   */
+  asks(key: string): Ask[] {
+    const dir = this.asksPath(key)
+    if (!existsSync(dir)) return []
+    const asks: Omit<Ask, "ordinal">[] = []
+    for (const entry of readdirSync(dir)) {
+      if (!entry.endsWith(".md") || entry.startsWith(".")) continue
+      const path = join(dir, entry)
+      const doc = parseAsk(readFileSync(path, "utf8"), path)
+      asks.push({
+        id: entry.slice(0, -3),
+        taskId: this.displayId(key),
+        text: doc.body,
+        author: doc.author,
+        createdAt: doc.createdAt,
+        resolvedAt: doc.resolvedAt,
+        resolvedBy: doc.resolvedBy,
+      })
+    }
+    asks.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id))
+    return asks.map((ask, index) => ({ ...ask, ordinal: index + 1 }))
+  }
+
+  /**
+   * File an ask — allowed only while the ticket is open. A done ticket can't
+   * quietly start owing things again (that's the NIC-17 failure this feature
+   * exists to end): reopen it, or file the ask as a new ticket.
+   */
+  addAsk(key: string, text: string, author = ""): Ask {
+    const ticket = this.readOne(key)
+    if (!ticket) {
+      this.assertNotArchived(key)
+      throw new Error(`no such task: ${this.displayId(key)}`)
+    }
+    if (ticket.doc.status === "done" || ticket.doc.status === "canceled") {
+      throw new Error(
+        `${this.displayId(key)} is ${ticket.doc.status} — asks belong on open tickets. Reopen it, or file the ask as a new ticket`,
+      )
+    }
+    const createdAt = now()
+    const dir = this.asksPath(key)
+    mkdirSync(dir, { recursive: true })
+    const stem = commentStem(createdAt, author)
+    let id = stem
+    for (let n = 2; existsSync(join(dir, `${id}.md`)); n++) id = `${stem}-${n}`
+    const doc: AskDoc = { author, createdAt, resolvedAt: null, resolvedBy: null, body: text }
+    writeAtomic(join(dir, `${id}.md`), serializeAsk(doc))
+    return this.asks(key).find((a) => a.id === id)!
+  }
+
+  /**
+   * Resolve an ask against the current listing — `ref` is an ordinal ("2") or
+   * the ask's id. Resolution edits the ask's own file, so the person's answer
+   * and the worker's question live in one place whatever branch each came from.
+   */
+  resolveAsk(key: string, ref: string, resolvedBy = ""): Ask {
+    return this.setAskResolution(key, ref, now(), resolvedBy)
+  }
+
+  /** Reopen a resolved ask — same refusals as adding one. */
+  reopenAsk(key: string, ref: string): Ask {
+    return this.setAskResolution(key, ref, null, null)
+  }
+
+  private setAskResolution(
+    key: string,
+    ref: string,
+    resolvedAt: string | null,
+    resolvedBy: string | null,
+  ): Ask {
+    this.assertNotArchived(key)
+    const ask = this.findAsk(key, ref)
+    const ticket = this.readOne(key)
+    if (
+      resolvedAt === null &&
+      (ticket?.doc.status === "done" || ticket?.doc.status === "canceled")
+    ) {
+      throw new Error(
+        `${this.displayId(key)} is ${ticket.doc.status} — reopening an ask would leave a finished ticket owing something. Reopen the ticket first, or file a new one`,
+      )
+    }
+    const doc: AskDoc = {
+      author: ask.author,
+      createdAt: ask.createdAt,
+      resolvedAt,
+      resolvedBy: resolvedAt === null ? null : resolvedBy,
+      body: ask.text,
+    }
+    writeAtomic(join(this.asksPath(key), `${ask.id}.md`), serializeAsk(doc))
+    return this.asks(key).find((a) => a.id === ask.id)!
+  }
+
+  deleteAsk(key: string, ref: string): Ask {
+    this.assertNotArchived(key)
+    const ask = this.findAsk(key, ref)
+    rmSync(join(this.asksPath(key), `${ask.id}.md`))
+    return ask
+  }
+
+  /**
+   * Resolve an ordinal or id against the directory listing rather than
+   * building a path from it — same rule as comment ids, the ref arrived over
+   * HTTP or a shell and must not point anywhere but at this ticket's asks.
+   */
+  private findAsk(key: string, ref: string): Ask {
+    const asks = this.asks(key)
+    const trimmed = ref.trim()
+    const byOrdinal = /^\d+$/.test(trimmed)
+      ? asks.find((a) => a.ordinal === Number(trimmed))
+      : undefined
+    const ask = byOrdinal ?? asks.find((a) => a.id === trimmed)
+    if (!ask) {
+      const id = this.displayId(key)
+      throw new Error(
+        asks.length === 0
+          ? `${id} has no asks`
+          : `no such ask on ${id}: ${ref} — ordinals run 1-${asks.length} (\`task show ${id}\` lists them)`,
+      )
+    }
+    return ask
+  }
+}
+
+/** The list() tiebreak, restated over Task — creation time, then key. */
+function byCreationTask(a: Task, b: Task): number {
+  return a.createdAt.localeCompare(b.createdAt) || a.key.localeCompare(b.key)
 }
 
 // ── Opening and initializing ─────────────────────────────────────────────────
@@ -767,6 +968,18 @@ export function openBoard(root: string): Store {
         "this board still stores its state in a pre-0.6 SQLite database — run `npx @nickmeriano/task@0.6 migrate` once, then retry",
       )
     }
+  } else {
+    // A board whose tickets are ALL numeric directories predates the TAS-42
+    // id cutover. Reading it as empty (the reader skips numeric dirs) would
+    // silently strand every ticket — refuse loudly instead, same policy as
+    // the SQLite case. A mixed board (a stray numeric dir merged in from an
+    // old branch) still opens; `task check` names the straggler.
+    const entries = readdirSync(join(taskDir, TICKETS_DIR))
+    if (entries.some((name) => /^\d+$/.test(name)) && !entries.some(isTicketKey)) {
+      throw new Error(
+        "this board's tickets use the pre-TAS-42 sequential-id format, which is no longer read — run the id migration (tools/migrate-ids/migrate.mjs in the repo that ships this board, or the migration script from the release notes) once, then retry",
+      )
+    }
   }
   return new FileStore(root)
 }
@@ -796,4 +1009,3 @@ export function initProject(root: string, options: InitOptions): Store {
   writeFileSync(join(taskDir, ".gitignore"), GITIGNORE)
   return new FileStore(root)
 }
-