@nickmeriano/task 0.7.1 → 0.9.0

package/dist/file-store.js

@@ -1,12 +1,18 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { commentStem, parseComment, parseTicket, serializeComment, serializeTicket, } from "./ticket-doc.js";
-import { CONFIG_FILE, DB_FILE, POSITION_GAP, TASK_DIR, TaskStore, derivePrefix, } from "./store.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";
-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() {
     return new Date().toISOString();
 }
@@ -19,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
@@ -38,104 +53,127 @@ export class FileStore {
     config;
     ticketsDir;
     archiveDir;
+    goalsDir;
+    goalsArchiveDir;
     constructor(root) {
         this.root = root;
         this.taskDir = join(root, TASK_DIR);
         this.config = JSON.parse(readFileSync(join(this.taskDir, CONFIG_FILE), "utf8"));
         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() { }
-    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);
     }
-    isArchived(number) {
-        return existsSync(join(this.archiveDir, String(number), TICKET_FILE));
+    liveKeys() {
+        return this.keysIn(this.ticketsDir);
+    }
+    /** 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,
-            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,
@@ -147,11 +185,13 @@ export class FileStore {
             const wanted = new Set(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);
@@ -168,52 +208,58 @@ 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;
-        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 = {
-            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,
@@ -222,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)}`);
             }
@@ -248,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;
@@ -263,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;
@@ -274,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)
@@ -284,19 +330,32 @@ export class FileStore {
             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);
             }
@@ -308,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);
@@ -345,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);
         }
     }
@@ -384,36 +443,192 @@ 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);
-    }
-    unarchive(number) {
-        if (!this.isArchived(number)) {
-            throw new Error(this.readOne(number)
-                ? `${this.displayId(number)} isn't archived`
-                : `no such task: ${this.displayId(number)}`);
+        renameSync(join(this.ticketsDir, key), join(this.archiveDir, key));
+        return this.get(key);
+    }
+    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) {
+        return join(archived ? this.goalsArchiveDir : this.goalsDir, `${slug}.md`);
+    }
+    readGoalDir(archived) {
+        const dir = archived ? this.goalsArchiveDir : this.goalsDir;
+        if (!existsSync(dir))
+            return [];
+        const goals = [];
+        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;
+    }
+    toGoal(slug, doc, archived) {
+        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) {
+        return this.readGoalDir(archived);
+    }
+    getGoal(slug) {
+        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.
+     */
+    assertGoalAssignable(slug) {
+        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\``);
+    }
+    writeGoal(slug, doc, archived) {
+        mkdirSync(archived ? this.goalsArchiveDir : this.goalsDir, { recursive: true });
+        writeAtomic(this.goalPath(slug, archived), serializeGoal(doc));
+    }
+    createGoal(input) {
+        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 = {
+            title,
+            description: input.description ?? "",
+            createdAt: timestamp,
+            updatedAt: timestamp,
+        };
+        this.writeGoal(slug, doc, false);
+        return this.toGoal(slug, doc, false);
+    }
+    updateGoal(slug, patch) {
+        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) {
+        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) {
+        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) {
+        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 ───────────────────────────────────────────────────────────────
     /**
@@ -421,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 = [];
@@ -433,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,
@@ -442,68 +657,205 @@ 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;
+    }
 }
-// ── Opening, initializing, migrating ─────────────────────────────────────────
+/** 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. */
+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
 *.tmp
 `;
 /**
- * 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) {
     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"));
-    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"));
+        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);
 }
 /**
  * Create `.task/` in `root`: config and a .gitignore. New boards are
@@ -525,80 +877,4 @@ export function initProject(root, options) {
     writeFileSync(join(taskDir, ".gitignore"), GITIGNORE);
     return new FileStore(root);
 }
-/**
- * `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) {
-    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 = 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"));
-        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();
-    }
-}
 //# sourceMappingURL=file-store.js.map