@nickmeriano/task 0.7.1 → 0.9.0

package/src/file-store.ts

@@ -10,23 +10,34 @@ import {
 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,
-  DB_FILE,
   POSITION_GAP,
   TASK_DIR,
-  TaskStore,
   derivePrefix,
   type Store,
 } from "./store.ts"
 import type {
+  Ask,
   Comment,
+  Goal,
+  GoalInput,
+  GoalPatch,
   ProjectConfig,
   Status,
   Task,
@@ -38,8 +49,13 @@ import type {
 export const TICKETS_DIR = "tickets"
 /** Finished tickets moved out of the hot path — same per-ticket layout. */
 export const ARCHIVE_DIR = "archive"
-const TICKET_FILE = "ticket.md"
-const COMMENTS_DIR = "comments"
+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"
 
 function now(): string {
   return new Date().toISOString()
@@ -56,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
@@ -79,6 +106,8 @@ export class FileStore implements Store {
   readonly config: ProjectConfig
   private ticketsDir: string
   private archiveDir: string
+  private goalsDir: string
+  private goalsArchiveDir: string
 
   constructor(root: string) {
     this.root = root
@@ -88,48 +117,63 @@ export class FileStore implements Store {
     ) as ProjectConfig
     this.ticketsDir = join(this.taskDir, TICKETS_DIR)
     this.archiveDir = join(this.taskDir, ARCHIVE_DIR)
+    this.goalsDir = join(this.taskDir, GOALS_DIR)
+    this.goalsArchiveDir = join(this.goalsDir, GOALS_ARCHIVE_DIR)
   }
 
   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
   }
 
@@ -138,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 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(number: number): boolean {
-    return existsSync(join(this.archiveDir, String(number), TICKET_FILE))
+  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,
-      milestone: ticket.doc.milestone,
-      needsHuman: ticket.doc.needsHuman,
+      goal: ticket.doc.goal,
+      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,
@@ -200,11 +254,15 @@ export class FileStore implements Store {
       const wanted = new Set<Status>(filter.statuses)
       tickets = tickets.filter((t) => wanted.has(t.doc.status))
     }
-    if (filter.milestone) {
-      tickets = tickets.filter((t) => t.doc.milestone === filter.milestone)
+    if (filter.goal) {
+      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)
@@ -222,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 }
   }
 
@@ -245,30 +304,33 @@ 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
-    const status = input.status ?? "todo"
+    // 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)}`)
       }
     }
+    if (input.goal) this.assertGoalAssignable(input.goal)
     // New tasks land at the bottom of their column.
     const column = all.filter((t) => t.doc.status === status)
     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 ?? [],
-        milestone: input.milestone ?? null,
-        needsHuman: input.needsHuman ?? false,
-        blockedBy: [...new Set(input.blockedBy ?? [])].sort((a, b) => a - b),
+        goal: input.goal ?? null,
+        blockedBy: sortKeys([...new Set(input.blockedBy ?? [])]),
         prs: input.prs ?? [],
         position: bottom + POSITION_GAP,
         createdAt: timestamp,
@@ -277,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)}`)
       }
@@ -306,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
@@ -321,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)
@@ -332,24 +394,40 @@ 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
     }
 
     if (patch.title !== undefined) set("title", patch.title)
     if (patch.description !== undefined) set("description", patch.description)
     if (patch.tags !== undefined) set("tags", patch.tags)
-    if (patch.milestone !== undefined) set("milestone", patch.milestone)
-    if (patch.needsHuman !== undefined) set("needsHuman", patch.needsHuman)
+    if (patch.goal !== undefined) {
+      if (patch.goal) this.assertGoalAssignable(patch.goal)
+      set("goal", patch.goal)
+    }
     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)
       }
@@ -359,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)!
   }
 
   /**
@@ -368,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)
@@ -401,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)
     }
   }
@@ -442,41 +520,210 @@ 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 ──────────────────────────────────────────────────────────────────
+
+  private goalPath(slug: string, archived: boolean): string {
+    return join(archived ? this.goalsArchiveDir : this.goalsDir, `${slug}.md`)
+  }
+
+  private readGoalDir(archived: boolean): Goal[] {
+    const dir = archived ? this.goalsArchiveDir : this.goalsDir
+    if (!existsSync(dir)) return []
+    const goals: Goal[] = []
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith(".md") || entry.name.startsWith(".")) continue
+      const slug = entry.name.slice(0, -3)
+      const path = join(dir, entry.name)
+      const doc = parseGoal(readFileSync(path, "utf8"), path)
+      goals.push(this.toGoal(slug, doc, archived))
+    }
+    goals.sort((a, b) => a.slug.localeCompare(b.slug))
+    return goals
+  }
+
+  private toGoal(slug: string, doc: GoalDoc, archived: boolean): Goal {
+    return {
+      slug,
+      title: doc.title,
+      description: doc.description,
+      createdAt: doc.createdAt,
+      updatedAt: doc.updatedAt,
+      // Absent on live goals, so existing payloads carry no new field.
+      ...(archived ? { archived: true } : {}),
+    }
+  }
+
+  goals(archived = false): Goal[] {
+    return this.readGoalDir(archived)
+  }
+
+  getGoal(slug: string): Goal | null {
+    for (const archived of [false, true]) {
+      const path = this.goalPath(slug, archived)
+      if (!existsSync(path)) continue
+      return this.toGoal(slug, parseGoal(readFileSync(path, "utf8"), path), archived)
+    }
+    return null
+  }
+
+  /**
+   * The gate every ticket write goes through: a `goal:` may only reference a
+   * *live* goal. Naming an archived one is refused too — assigning new work to
+   * a goal that's been shelved is the same mistake as editing an archived
+   * ticket, and gets the same answer.
+   */
+  private assertGoalAssignable(slug: string): void {
+    if (existsSync(this.goalPath(slug, false))) return
+    if (existsSync(this.goalPath(slug, true))) {
+      throw new Error(`goal "${slug}" is archived — run \`task goal unarchive ${slug}\` first`)
+    }
+    throw new Error(`no such goal: "${slug}" — create it with \`task goal add\``)
+  }
+
+  private writeGoal(slug: string, doc: GoalDoc, archived: boolean): void {
+    mkdirSync(archived ? this.goalsArchiveDir : this.goalsDir, { recursive: true })
+    writeAtomic(this.goalPath(slug, archived), serializeGoal(doc))
+  }
+
+  createGoal(input: GoalInput): Goal {
+    const title = input.title.trim()
+    if (!title) throw new Error("a goal needs a title")
+    const slug = input.slug ?? slugifyGoal(title)
+    if (!isGoalSlug(slug)) {
+      throw new Error(
+        `invalid goal slug: "${slug}" — lowercase letters, digits and dashes ("archive" is reserved)`,
+      )
+    }
+    if (this.getGoal(slug)) throw new Error(`goal "${slug}" already exists`)
+    const timestamp = now()
+    const doc: GoalDoc = {
+      title,
+      description: input.description ?? "",
+      createdAt: timestamp,
+      updatedAt: timestamp,
+    }
+    this.writeGoal(slug, doc, false)
+    return this.toGoal(slug, doc, false)
+  }
+
+  updateGoal(slug: string, patch: GoalPatch): Goal {
+    const path = this.goalPath(slug, false)
+    if (!existsSync(path)) {
+      if (existsSync(this.goalPath(slug, true))) {
+        throw new Error(`goal "${slug}" is archived — run \`task goal unarchive ${slug}\` first`)
+      }
+      throw new Error(`no such goal: "${slug}"`)
+    }
+    const doc = parseGoal(readFileSync(path, "utf8"), path)
+    if (patch.title !== undefined) {
+      const title = patch.title.trim()
+      if (!title) throw new Error("a goal needs a title")
+      doc.title = title
+    }
+    if (patch.description !== undefined) doc.description = patch.description
+    doc.updatedAt = now()
+    this.writeGoal(slug, doc, false)
+    return this.toGoal(slug, doc, false)
+  }
+
+  /**
+   * A goal leaves the board only after its work has: archiving is refused
+   * while any open task still points here. Done/canceled stragglers are fine —
+   * their references stay readable from the archive either way.
+   */
+  archiveGoal(slug: string): Goal {
+    const path = this.goalPath(slug, false)
+    if (!existsSync(path)) {
+      if (existsSync(this.goalPath(slug, true))) {
+        throw new Error(`goal "${slug}" is already archived`)
+      }
+      throw new Error(`no such goal: "${slug}"`)
+    }
+    const open = this.readAll().filter(
+      (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.key)).join(", ")
+      throw new Error(`goal "${slug}" still has open tasks (${ids}) — finish or reassign them first`)
+    }
+    mkdirSync(this.goalsArchiveDir, { recursive: true })
+    renameSync(path, this.goalPath(slug, true))
+    return this.getGoal(slug)!
+  }
+
+  unarchiveGoal(slug: string): Goal {
+    const path = this.goalPath(slug, true)
+    if (!existsSync(path)) {
+      throw new Error(
+        existsSync(this.goalPath(slug, false))
+          ? `goal "${slug}" isn't archived`
+          : `no such goal: "${slug}"`,
+      )
+    }
+    mkdirSync(this.goalsDir, { recursive: true })
+    renameSync(path, this.goalPath(slug, false))
+    return this.getGoal(slug)!
+  }
+
+  /**
+   * Deleting is for goals that never happened. Any live reference — whatever
+   * its status — blocks it: pruning organization off finished tickets is a
+   * human call, so the human makes it by clearing the refs first. Archived
+   * tickets' references are left to dangle; every reader tolerates that.
+   */
+  deleteGoal(slug: string): void {
+    const path = this.goalPath(slug, false)
+    if (!existsSync(path)) {
+      if (existsSync(this.goalPath(slug, true))) {
+        throw new Error(`goal "${slug}" is archived — run \`task goal unarchive ${slug}\` first`)
+      }
+      throw new Error(`no such goal: "${slug}"`)
+    }
+    const referencing = this.readAll().filter((t) => t.doc.goal === slug)
+    if (referencing.length > 0) {
+      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`,
+      )
+    }
+    rmSync(path)
   }
 
   // ── Comments ───────────────────────────────────────────────────────────────
@@ -486,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)) {
@@ -496,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,
@@ -508,53 +755,198 @@ 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, initializing, migrating ─────────────────────────────────────────
+// ── Opening and initializing ─────────────────────────────────────────────────
+
+/** The database a pre-0.6 board committed. Never read anymore, only ignored. */
+const LEGACY_DB_FILE = "tasks.db"
 
 /** What `.task/.gitignore` says on a text-canonical board. */
 const GITIGNORE = `# Board state is the text files in tickets/ — the database (if one is still
-# around from before \`task migrate\`) is derived/legacy and stays out of git.
-${DB_FILE}
+# around from a pre-0.6 board) is legacy and stays out of git.
+${LEGACY_DB_FILE}
 *.db-journal
 *.db-wal
 *.db-shm
@@ -562,16 +954,34 @@ ${DB_FILE}
 `
 
 /**
- * The board in `root`, on whichever backend it uses: text files when the
- * `tickets/` tree exists or the config says version ≥ 2, the legacy SQLite
- * store otherwise. Old boards keep working untouched until `task migrate`.
+ * The board in `root`. Text files are the only backend; a board whose state is
+ * still a pre-0.6 committed SQLite database is refused loudly rather than read
+ * as empty — silently starting a parallel text board next to a database full
+ * of tickets is the one failure mode worse than an error.
  */
 export function openBoard(root: string): Store {
   const taskDir = join(root, TASK_DIR)
-  if (existsSync(join(taskDir, TICKETS_DIR))) return new FileStore(root)
-  const config = JSON.parse(readFileSync(join(taskDir, CONFIG_FILE), "utf8")) as ProjectConfig
-  if ((config.version ?? 1) >= 2) return new FileStore(root)
-  return new TaskStore(root)
+  if (!existsSync(join(taskDir, TICKETS_DIR))) {
+    const config = JSON.parse(readFileSync(join(taskDir, CONFIG_FILE), "utf8")) as ProjectConfig
+    if ((config.version ?? 1) < 2 && existsSync(join(taskDir, LEGACY_DB_FILE))) {
+      throw new Error(
+        "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)
 }
 
 export interface InitOptions {
@@ -599,95 +1009,3 @@ export function initProject(root: string, options: InitOptions): Store {
   writeFileSync(join(taskDir, ".gitignore"), GITIGNORE)
   return new FileStore(root)
 }
-
-export interface MigrateResult {
-  tasks: number
-  comments: number
-}
-
-/**
- * `task migrate` — export every ticket and comment from a legacy `tasks.db`
- * into the text layout, flip the config to version 2, and gitignore the
- * database. The database file itself is left on disk untouched, as a backup;
- * it just stops being the state.
- */
-export function migrateBoard(root: string): MigrateResult {
-  const taskDir = join(root, TASK_DIR)
-  if (existsSync(join(taskDir, TICKETS_DIR))) {
-    throw new Error("already migrated — .task/tickets/ exists")
-  }
-  if (!existsSync(join(taskDir, DB_FILE))) {
-    throw new Error(`nothing to migrate — no ${DB_FILE} in .task/`)
-  }
-
-  const legacy = new TaskStore(root)
-  let comments = 0
-  try {
-    const tasks = legacy.list({})
-    for (const task of tasks) {
-      const dir = join(taskDir, TICKETS_DIR, String(task.number))
-      mkdirSync(dir, { recursive: true })
-      writeFileSync(
-        join(dir, TICKET_FILE),
-        serializeTicket({
-          title: task.title,
-          description: task.description,
-          status: task.status,
-          tags: task.tags,
-          milestone: task.milestone,
-          needsHuman: task.needsHuman,
-          blockedBy: task.blockedBy,
-          prs: task.prs,
-          position: task.position,
-          createdAt: task.createdAt,
-          updatedAt: task.updatedAt,
-        }),
-      )
-      const taskComments = legacy.comments(task.number)
-      if (taskComments.length === 0) continue
-      const commentsDir = join(dir, COMMENTS_DIR)
-      mkdirSync(commentsDir)
-      let previous: { createdAt: string; id: string } | null = null
-      for (const comment of taskComments) {
-        // `comments()` sorts by (createdAt, id), so ids must sort in legacy
-        // (rowid) order wherever timestamps tie — and a fresh stem for a
-        // different author can sort *before* the previous one. Chain off the
-        // previous id instead: the collision suffix below then appends `-2`,
-        // which sorts after. The frontmatter stays authoritative for the
-        // author; the filename is only an ordering key.
-        let stem = commentStem(comment.createdAt, comment.author)
-        if (
-          previous &&
-          comment.createdAt === previous.createdAt &&
-          stem.localeCompare(previous.id) < 0
-        ) {
-          stem = previous.id
-        }
-        let id = stem
-        for (let n = 2; existsSync(join(commentsDir, `${id}.md`)); n++) id = `${stem}-${n}`
-        previous = { createdAt: comment.createdAt, id }
-        writeFileSync(
-          join(commentsDir, `${id}.md`),
-          serializeComment({
-            author: comment.author,
-            createdAt: comment.createdAt,
-            body: comment.body,
-          }),
-        )
-        comments++
-      }
-    }
-
-    // Preserve whatever else the config carries; only the version flips.
-    const config = JSON.parse(readFileSync(join(taskDir, CONFIG_FILE), "utf8")) as Record<
-      string,
-      unknown
-    >
-    config.version = 2
-    writeFileSync(join(taskDir, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`)
-    writeFileSync(join(taskDir, ".gitignore"), GITIGNORE)
-    return { tasks: tasks.length, comments }
-  } finally {
-    legacy.close()
-  }
-}