@nickmeriano/task 0.8.0 → 0.9.0

package/dist/file-store.js

@@ -1,12 +1,15 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { commentStem, isGoalSlug, parseComment, parseGoal, parseTicket, serializeComment, serializeGoal, serializeTicket, slugifyGoal, } from "./ticket-doc.js";
+import { commentStem, isGoalSlug, parseAsk, parseComment, parseGoal, parseTicket, serializeAsk, serializeComment, serializeGoal, serializeTicket, slugifyGoal, } from "./ticket-doc.js";
+import { isTicketKey, mintKey } from "./id.js";
 import { CONFIG_FILE, POSITION_GAP, TASK_DIR, derivePrefix, } from "./store.js";
 export const TICKETS_DIR = "tickets";
 /** Finished tickets moved out of the hot path — same per-ticket layout. */
 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";
@@ -22,13 +25,22 @@ function writeAtomic(path, text) {
     writeFileSync(tmp, text);
     renameSync(tmp, path);
 }
+/** Stable sort for key lists — lexicographic, since keys carry no order. */
+function sortKeys(keys) {
+    return keys.sort((a, b) => a.localeCompare(b));
+}
+/** Board order's tiebreak: creation time, then key — keys themselves say nothing. */
+function byCreation(a, b) {
+    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
@@ -53,96 +65,115 @@ export class FileStore {
         this.goalsArchiveDir = join(this.goalsDir, GOALS_ARCHIVE_DIR);
     }
     close() { }
-    displayId(number) {
-        return `${this.config.prefix}-${number}`;
+    displayId(key) {
+        return `${this.config.prefix}-${key}`;
     }
-    /** Accepts "PHONE-12", "phone-12" or "12". */
+    /**
+     * "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) {
-        const match = /^(?:[A-Za-z0-9]+-)?(\d+)$/.exec(ref.trim());
+        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 ────────────────────────────────────────────────────────────────
-    ticketPath(number) {
-        return join(this.ticketsDir, String(number), TICKET_FILE);
+    ticketPath(key) {
+        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.
      */
-    commentsPath(number) {
-        const home = existsSync(join(this.archiveDir, String(number)))
-            ? this.archiveDir
-            : this.ticketsDir;
-        return join(home, String(number), COMMENTS_DIR);
+    commentsPath(key) {
+        const home = existsSync(join(this.archiveDir, key)) ? this.archiveDir : this.ticketsDir;
+        return join(home, key, COMMENTS_DIR);
     }
     readDir(dir) {
         if (!existsSync(dir))
             return [];
         const tickets = [];
         for (const entry of readdirSync(dir, { withFileTypes: true })) {
-            if (!entry.isDirectory() || !/^\d+$/.test(entry.name))
+            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;
     }
     /** Every live ticket on the board, freshly parsed — the files are the state. */
     readAll() {
         return this.readDir(this.ticketsDir);
     }
-    readOne(number) {
-        const path = this.ticketPath(number);
-        if (!existsSync(path))
+    readOne(key) {
+        const path = this.ticketPath(key);
+        if (!isTicketKey(key) || !existsSync(path))
             return null;
-        return { number, doc: parseTicket(readFileSync(path, "utf8"), path) };
+        return { key, doc: parseTicket(readFileSync(path, "utf8"), path) };
     }
-    /** Cheap presence check — the archive's numbers, without parsing anything. */
-    archivedNumbers() {
-        if (!existsSync(this.archiveDir))
+    /** Directory names that are well-formed keys, without parsing anything. */
+    keysIn(dir) {
+        if (!existsSync(dir))
             return [];
-        return readdirSync(this.archiveDir)
-            .filter((name) => /^\d+$/.test(name))
-            .map(Number);
+        return readdirSync(dir).filter(isTicketKey);
+    }
+    liveKeys() {
+        return this.keysIn(this.ticketsDir);
     }
-    isArchived(number) {
-        return existsSync(join(this.archiveDir, String(number), TICKET_FILE));
+    /** Cheap presence check — the archive's keys, without parsing anything. */
+    archivedKeys() {
+        return this.keysIn(this.archiveDir);
+    }
+    isArchived(key) {
+        return isTicketKey(key) && existsSync(join(this.archiveDir, key, TICKET_FILE));
     }
     /** The error every write path throws instead of touching the archive. */
-    assertNotArchived(number) {
-        if (this.isArchived(number)) {
-            const id = this.displayId(number);
+    assertNotArchived(key) {
+        if (this.isArchived(key)) {
+            const id = this.displayId(key);
             throw new Error(`${id} is archived — run \`task unarchive ${id}\` first`);
         }
     }
     writeTicket(ticket) {
-        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.
      */
-    toTask(ticket, all) {
-        const blocks = all
-            .filter((t) => t.doc.blockedBy.includes(ticket.number))
-            .map((t) => t.number);
+    toTask(ticket, all, asks = this.asks(ticket.key)) {
+        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,
@@ -158,7 +189,9 @@ export class FileStore {
             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);
@@ -175,37 +208,40 @@ export class FileStore {
             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) {
+    get(key) {
         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 = { number, doc: parseTicket(readFileSync(path, "utf8"), path) };
+        const archived = { key, doc: parseTicket(readFileSync(path, "utf8"), path) };
         return { ...this.toTask(archived, [...all, archived]), archived: true };
     }
     // ── Writing ────────────────────────────────────────────────────────────────
     create(input) {
         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)}`);
             }
         }
@@ -216,15 +252,14 @@ export class FileStore {
         const bottom = column.length ? Math.max(...column.map((t) => t.doc.position)) : 0;
         const timestamp = now();
         const 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,
@@ -233,25 +268,25 @@ export class FileStore {
         };
         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, patch) {
+    update(key, patch) {
         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)}`);
             }
@@ -259,14 +294,14 @@ export class FileStore {
         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;
@@ -274,8 +309,8 @@ export class FileStore {
                 // 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;
@@ -285,8 +320,8 @@ export class FileStore {
         }
         const doc = ticket.doc;
         let fieldsChanged = false;
-        const set = (key, value) => {
-            doc[key] = value;
+        const set = (field, value) => {
+            doc[field] = value;
             fieldsChanged = true;
         };
         if (patch.title !== undefined)
@@ -300,17 +335,27 @@ export class FileStore {
                 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);
             }
@@ -322,35 +367,35 @@ export class FileStore {
         if (fieldsChanged || linksChanged)
             doc.updatedAt = timestamp;
         this.writeTicket(ticket);
-        return this.get(number);
+        return this.get(key);
     }
     /**
      * Make every other ticket's `blocked_by` agree with "this task blocks
      * exactly `targets`". Returns whether anything changed; every touched ticket
      * (and, via the caller, this one) gets its `updated` bumped.
      */
-    reconcileBlocks(number, all, targets, timestamp) {
+    reconcileBlocks(key, all, targets, timestamp) {
         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)
+            if (other.key === key)
                 continue;
-            const has = other.doc.blockedBy.includes(number);
-            const should = wanted.has(other.number);
+            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);
@@ -359,37 +404,37 @@ export class FileStore {
         return changed;
     }
     /** `task link A --blocks B` and friends — additive, unlike the patch form. */
-    link(number, relation, target) {
-        const task = this.get(number);
+    link(key, relation, target) {
+        const task = this.get(key);
         if (!task)
-            throw new Error(`no such task: ${this.displayId(number)}`);
+            throw new Error(`no such task: ${this.displayId(key)}`);
         const current = relation === "blocks" ? task.blocks : task.blockedBy;
         const patch = relation === "blocks"
             ? { blocks: [...current, target] }
             : { blockedBy: [...current, target] };
-        return this.update(number, patch);
+        return this.update(key, patch);
     }
-    unlink(number, relation, target) {
-        const task = this.get(number);
+    unlink(key, relation, target) {
+        const task = this.get(key);
         if (!task)
-            throw new Error(`no such task: ${this.displayId(number)}`);
+            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 = relation === "blocks" ? { blocks: kept } : { blockedBy: kept };
-        return this.update(number, patch);
+        return this.update(key, patch);
     }
-    delete(number) {
-        if (!this.readOne(number)) {
-            this.assertNotArchived(number);
-            throw new Error(`no such task: ${this.displayId(number)}`);
+    delete(key) {
+        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))
+            if (!other.doc.blockedBy.includes(key))
                 continue;
-            other.doc.blockedBy = other.doc.blockedBy.filter((n) => n !== number);
+            other.doc.blockedBy = other.doc.blockedBy.filter((k) => k !== key);
             this.writeTicket(other);
         }
     }
@@ -398,36 +443,36 @@ export class FileStore {
      * 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) {
-        const ticket = this.readOne(number);
+    archive(key) {
+        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`);
+            throw new Error(`${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) {
-        if (!this.isArchived(number)) {
-            throw new Error(this.readOne(number)
-                ? `${this.displayId(number)} isn't archived`
-                : `no such task: ${this.displayId(number)}`);
+    unarchive(key) {
+        if (!this.isArchived(key)) {
+            throw new Error(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 ──────────────────────────────────────────────────────────────────
     goalPath(slug, archived) {
@@ -546,7 +591,7 @@ export class FileStore {
         }
         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.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 });
@@ -580,7 +625,7 @@ export class FileStore {
         }
         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`);
         }
         rmSync(path);
@@ -591,8 +636,8 @@ export class FileStore {
      * the same ticket produce two files and merge without a conflict — which is
      * why they aren't lines inside `ticket.md`.
      */
-    comments(number) {
-        const dir = this.commentsPath(number);
+    comments(key) {
+        const dir = this.commentsPath(key);
         if (!existsSync(dir))
             return [];
         const comments = [];
@@ -603,7 +648,7 @@ export class FileStore {
             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,
@@ -612,44 +657,166 @@ export class FileStore {
         comments.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
         return comments;
     }
-    addComment(number, body, author = "") {
-        if (!this.readOne(number)) {
-            this.assertNotArchived(number);
-            throw new Error(`no such task: ${this.displayId(number)}`);
+    addComment(key, body, author = "") {
+        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, commentId) {
+    deleteComment(key, commentId) {
         // 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() {
         const counts = new Map();
         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);
+                counts.set(ticket.key, count);
         }
         return counts;
     }
+    // ── Asks ───────────────────────────────────────────────────────────────────
+    /** Like comments, an archived ticket keeps its asks readable in place. */
+    asksPath(key) {
+        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) {
+        const dir = this.asksPath(key);
+        if (!existsSync(dir))
+            return [];
+        const asks = [];
+        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, text, author = "") {
+        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 = { 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, ref, resolvedBy = "") {
+        return this.setAskResolution(key, ref, now(), resolvedBy);
+    }
+    /** Reopen a resolved ask — same refusals as adding one. */
+    reopenAsk(key, ref) {
+        return this.setAskResolution(key, ref, null, null);
+    }
+    setAskResolution(key, ref, resolvedAt, resolvedBy) {
+        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 = {
+            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, ref) {
+        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.
+     */
+    findAsk(key, ref) {
+        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, b) {
+    return a.createdAt.localeCompare(b.createdAt) || a.key.localeCompare(b.key);
 }
 // ── Opening and initializing ─────────────────────────────────────────────────
 /** The database a pre-0.6 board committed. Never read anymore, only ignored. */
@@ -677,6 +844,17 @@ export function openBoard(root) {
             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);
 }
 /**