@nickmeriano/task 0.8.0 → 0.9.0

package/src/store.ts

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs"
 import { dirname, join, relative, sep } from "node:path"
 import type {
+  Ask,
   Comment,
   Goal,
   GoalInput,
@@ -29,18 +30,24 @@ export interface Store {
   readonly taskDir: string
   readonly config: ProjectConfig
   close(): void
-  displayId(number: number): string
-  parseId(ref: string): number
+  displayId(key: string): string
+  /**
+   * Resolve a ref — "TAS-x7k4m", "x7k4m", or a unique key prefix like "x7" —
+   * to a ticket key, git-style: any unambiguous prefix of an existing key
+   * works, an ambiguous one throws naming the candidates, and an unknown one
+   * comes back verbatim so the caller's lookup produces the "no such task".
+   */
+  parseId(ref: string): string
   list(filter?: TaskFilter): Task[]
-  get(number: number): Task | null
+  get(key: string): Task | null
   create(input: TaskInput): Task
-  update(number: number, patch: TaskPatch): Task
-  link(number: number, relation: "blocks" | "blocked_by", target: number): Task
-  unlink(number: number, relation: "blocks" | "blocked_by", target: number): Task
-  delete(number: number): void
+  update(key: string, patch: TaskPatch): Task
+  link(key: string, relation: "blocks" | "blocked_by", target: string): Task
+  unlink(key: string, relation: "blocks" | "blocked_by", target: string): Task
+  delete(key: string): void
   /** Move a done/canceled ticket to `.task/archive/`, out of the board's hot path. */
-  archive(number: number): Task
-  unarchive(number: number): Task
+  archive(key: string): Task
+  unarchive(key: string): Task
   /** Live goals, in slug order — pass `true` to list `.task/goals/archive/` instead. */
   goals(archived?: boolean): Goal[]
   /** Live or archived — a ticket's `goal:` ref should resolve either way. */
@@ -52,10 +59,18 @@ export interface Store {
   unarchiveGoal(slug: string): Goal
   /** Refused while any live task references the goal, whatever its status. */
   deleteGoal(slug: string): void
-  comments(number: number): Comment[]
-  addComment(number: number, body: string, author?: string): Comment
-  deleteComment(number: number, commentId: string): Comment
-  commentCounts(): Map<number, number>
+  comments(key: string): Comment[]
+  addComment(key: string, body: string, author?: string): Comment
+  deleteComment(key: string, commentId: string): Comment
+  commentCounts(): Map<string, number>
+  /** Every ask on a ticket, open and resolved, in creation (= ordinal) order. */
+  asks(key: string): Ask[]
+  /** Refused on done/canceled tickets — a finished ticket can't start owing again. */
+  addAsk(key: string, text: string, author?: string): Ask
+  /** `ref` is an ordinal ("2") or the ask's id. */
+  resolveAsk(key: string, ref: string, resolvedBy?: string): Ask
+  reopenAsk(key: string, ref: string): Ask
+  deleteAsk(key: string, ref: string): Ask
 }
 
 /**

package/src/ticket-doc.ts

@@ -25,9 +25,8 @@ export interface TicketDoc {
   tags: string[]
   /** Slug of the goal this ticket belongs to — at most one, by design. */
   goal: string | null
-  needsHuman: boolean
-  /** Task numbers blocking this one — the single stored side of the relation. */
-  blockedBy: number[]
+  /** Keys of tasks blocking this one — the single stored side of the relation. */
+  blockedBy: string[]
   prs: string[]
   position: number
   createdAt: string
@@ -41,18 +40,11 @@ export interface TicketDoc {
   extras?: [string, string][]
 }
 
-/**
- * The frontmatter keys a ticket file may carry; anything else is an extra.
- * `milestone` is the pre-0.8 spelling of `goal`: still *read* (as the goal, so
- * old boards keep rendering) but never written — `task check` flags it and
- * `--fix` rewrites the file, which is the whole migration.
- */
+/** The frontmatter keys a ticket file may carry; anything else is an extra. */
 export const TICKET_FIELDS = [
   "status",
   "tags",
   "goal",
-  "milestone",
-  "needs_human",
   "blocked_by",
   "prs",
   "position",
@@ -69,6 +61,22 @@ export interface CommentDoc {
   body: string
 }
 
+/** The frontmatter keys an ask file may carry. */
+export const ASK_FIELDS = ["author", "created", "resolved", "resolved_by"] as const
+
+/**
+ * One ask on disk — `tickets/<n>/asks/<stem>.md`, the comment layout plus a
+ * resolution: `resolved`/`resolved_by` appear when the ask is closed and are
+ * simply absent while it's open, so an open ask's bytes never churn.
+ */
+export interface AskDoc {
+  author: string
+  createdAt: string
+  resolvedAt: string | null
+  resolvedBy: string | null
+  body: string
+}
+
 /** A parse that names the file it failed in — these files invite hand-editing. */
 export class TicketParseError extends Error {}
 
@@ -144,13 +152,17 @@ function stringList(raw: RawDoc, key: string, where: string): string[] {
   throw new TicketParseError(`${where}: ${key} should be a list of strings, e.g. ["a", "b"]`)
 }
 
-function numberList(raw: RawDoc, key: string, where: string): number[] {
+function keyList(raw: RawDoc, key: string, where: string): string[] {
   const value = field(raw, key)
   if (value === undefined) return []
-  if (Array.isArray(value) && value.every((v) => typeof v === "number" && Number.isInteger(v))) {
-    return value as number[]
+  if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+    return value as string[]
   }
-  throw new TicketParseError(`${where}: ${key} should be a list of task numbers, e.g. [3, 7]`)
+  // A list of bare numbers is a pre-migration file (ids were sequential
+  // integers before TAS-42) — name the one edit that fixes it.
+  throw new TicketParseError(
+    `${where}: ${key} should be a list of ticket keys, e.g. ["x7k4m", "q3v8d"] — numeric entries are the pre-TAS-42 id format, which is no longer read`,
+  )
 }
 
 // ── Tickets ──────────────────────────────────────────────────────────────────
@@ -177,11 +189,18 @@ export function parseTicket(text: string, where: string): TicketDoc {
       `${where}: invalid status "${status}" — one of: ${STATUSES.join(", ")}`,
     )
   }
-  const goal = field(raw, "goal") ?? field(raw, "milestone")
+  // The pre-0.8 `milestone:` spelling is not honored (TAS-41: no compat), and
+  // reading past it would silently drop the ticket's goal — refuse by name
+  // instead, so the one edit that fixes the file is in the error.
+  if (raw.fields.has("milestone")) {
+    throw new TicketParseError(
+      `${where}: \`milestone:\` is the pre-0.8 spelling and is no longer read — rename the key to \`goal:\``,
+    )
+  }
+  const goal = field(raw, "goal")
   if (goal !== undefined && goal !== null && typeof goal !== "string") {
     throw new TicketParseError(`${where}: goal should be a string`)
   }
-  const needsHuman = field(raw, "needs_human")
   const position = field(raw, "position")
   if (position !== undefined && typeof position !== "number") {
     throw new TicketParseError(`${where}: position should be a number`)
@@ -201,8 +220,7 @@ export function parseTicket(text: string, where: string): TicketDoc {
     status,
     tags: stringList(raw, "tags", where),
     goal: typeof goal === "string" && goal !== "" ? goal : null,
-    needsHuman: needsHuman === true,
-    blockedBy: numberList(raw, "blocked_by", where),
+    blockedBy: keyList(raw, "blocked_by", where),
     prs: stringList(raw, "prs", where),
     position: typeof position === "number" ? position : 0,
     createdAt: stringField(raw, "created", where, ""),
@@ -226,7 +244,6 @@ export function serializeTicket(doc: TicketDoc): string {
   const lines = ["---", `status: ${doc.status}`]
   if (doc.tags.length) lines.push(`tags: ${list(doc.tags)}`)
   if (doc.goal) lines.push(`goal: ${JSON.stringify(doc.goal)}`)
-  if (doc.needsHuman) lines.push(`needs_human: true`)
   if (doc.blockedBy.length) lines.push(`blocked_by: ${list(doc.blockedBy)}`)
   if (doc.prs.length) lines.push(`prs: ${list(doc.prs)}`)
   lines.push(`position: ${doc.position}`)
@@ -339,6 +356,53 @@ export function serializeComment(doc: CommentDoc): string {
   return `${lines.join("\n")}\n`
 }
 
+// ── Asks ─────────────────────────────────────────────────────────────────────
+
+export function parseAsk(text: string, where: string): AskDoc {
+  const raw = splitRaw(text, where)!
+  const resolvedAt = field(raw, "resolved")
+  if (resolvedAt !== undefined && typeof resolvedAt !== "string") {
+    throw new TicketParseError(`${where}: resolved should be a timestamp string`)
+  }
+  return {
+    author: stringField(raw, "author", where, ""),
+    createdAt: stringField(raw, "created", where, ""),
+    resolvedAt: resolvedAt ?? null,
+    resolvedBy: resolvedAt === undefined ? null : stringField(raw, "resolved_by", where, ""),
+    body: raw.body,
+  }
+}
+
+export function serializeAsk(doc: AskDoc): string {
+  const lines = ["---"]
+  if (doc.author) lines.push(`author: ${JSON.stringify(doc.author)}`)
+  lines.push(`created: ${doc.createdAt}`)
+  if (doc.resolvedAt) {
+    lines.push(`resolved: ${doc.resolvedAt}`)
+    if (doc.resolvedBy) lines.push(`resolved_by: ${JSON.stringify(doc.resolvedBy)}`)
+  }
+  lines.push("---", "", doc.body)
+  return `${lines.join("\n")}\n`
+}
+
+/**
+ * An ask, forgivingly — null when there's no frontmatter at all. The lenient
+ * read matters more here than for comments: the inbox reads ask files straight
+ * off claim branches, which are exactly the bytes a strict parser can't refuse.
+ */
+export function parseAskLenient(text: string): AskDoc | null {
+  const raw = splitRaw(text, null)
+  if (!raw) return null
+  const resolvedAt = field(raw, "resolved")
+  return {
+    author: lenientString(field(raw, "author")),
+    createdAt: lenientString(field(raw, "created")),
+    resolvedAt: typeof resolvedAt === "string" && resolvedAt !== "" ? resolvedAt : null,
+    resolvedBy: lenientString(field(raw, "resolved_by")) || null,
+    body: raw.body,
+  }
+}
+
 // ── Lenient parsing ──────────────────────────────────────────────────────────
 //
 // The hosted board's read of the same format. The CLI is strict — it wrote the
@@ -352,10 +416,10 @@ function lenientStrings(value: unknown): string[] {
   return Array.isArray(value) ? value.filter((v): v is string => typeof v === "string") : []
 }
 
-function lenientNumbers(value: unknown): number[] {
-  return Array.isArray(value)
-    ? value.filter((v): v is number => typeof v === "number" && Number.isInteger(v))
-    : []
+function lenientKeys(value: unknown): string[] {
+  // Numeric entries (the pre-TAS-42 id format) are dropped, not coerced: a
+  // rendered old branch degrades to unlinked tickets, never to wrong links.
+  return Array.isArray(value) ? value.filter((v): v is string => typeof v === "string") : []
 }
 
 function lenientString(value: unknown): string {
@@ -367,10 +431,10 @@ export function parseTicketLenient(text: string): TicketDoc | null {
   const raw = splitRaw(text, null)
   if (!raw) return null
   const status = field(raw, "status")
-  // The pre-0.8 `milestone` key still reads as the goal — the lenient parser
-  // exists precisely for old bytes (hand-edits, and here: old branches the
-  // hosted board previews).
-  const goal = field(raw, "goal") ?? field(raw, "milestone")
+  // No `milestone:` read here either — on the old branches the hosted board
+  // previews, a pre-0.8 ticket degrades to goalless, the same as any other
+  // retired field. History renders; it doesn't get reinterpreted.
+  const goal = field(raw, "goal")
   const position = field(raw, "position")
   const { title, description } = splitTitle(raw.body)
   return {
@@ -379,8 +443,7 @@ export function parseTicketLenient(text: string): TicketDoc | null {
     status: typeof status === "string" && isStatus(status) ? status : "backlog",
     tags: lenientStrings(field(raw, "tags")),
     goal: typeof goal === "string" && goal !== "" ? goal : null,
-    needsHuman: field(raw, "needs_human") === true,
-    blockedBy: [...new Set(lenientNumbers(field(raw, "blocked_by")))].sort((a, b) => a - b),
+    blockedBy: [...new Set(lenientKeys(field(raw, "blocked_by")))].sort(),
     prs: lenientStrings(field(raw, "prs")),
     position: typeof position === "number" && Number.isFinite(position) ? position : 0,
     createdAt: lenientString(field(raw, "created")),

package/src/types.ts

@@ -9,10 +9,42 @@ export const STATUSES = [
 ] as const
 export type Status = (typeof STATUSES)[number]
 
+/**
+ * An ask: one thing a person owes this ticket before it can be done. Stored
+ * like a comment — one file per ask under `tickets/<n>/asks/` — so a worker on
+ * a claim branch can add one without ever conflicting with main. The ask is
+ * the primitive everything human-owed funnels through: `needsHuman` is derived
+ * from open asks, `task inbox` is the list of them, and `done` is gated on
+ * zero remaining.
+ */
+export interface Ask {
+  /** Stable opaque id — the ask's filename stem (e.g. "2026-08-27T104501-claude"). */
+  id: string
+  taskId: string
+  /**
+   * 1-based position in creation order across the ticket's asks, resolved and
+   * open alike — the short handle `task resolve <id> <ordinal>` takes.
+   */
+  ordinal: number
+  text: string
+  author: string
+  createdAt: string
+  /** Both null while the ask is open. */
+  resolvedAt: string | null
+  resolvedBy: string | null
+}
+
 export interface Task {
-  /** Display id — `<prefix>-<number>`, e.g. "PHO-12". */
+  /** Display id — `<prefix>-<key>`, e.g. "PHO-x7k4m". */
   id: string
-  number: number
+  /**
+   * The ticket's key: 5 random lowercase characters minted at creation (see
+   * id.ts), doubling as its directory name under `.task/tickets/`. Random on
+   * purpose — allocation must be safe across branches that have never seen
+   * each other — and opaque on purpose: creation order lives in `createdAt`,
+   * board order in `position`.
+   */
+  key: string
   title: string
   description: string
   status: Status
@@ -23,15 +55,20 @@ export interface Task {
    * wants to live in two goals is a tag.
    */
   goal: string | null
-  /** This ticket can't be finished by an agent alone. */
+  /**
+   * Derived, never stored: true while any ask is open. There is no flag to
+   * set — a flag with no stated reason is the failure mode asks exist to end.
+   */
   needsHuman: boolean
+  /** Every ask on this ticket, open and resolved, in creation order. */
+  asks: Ask[]
   /**
-   * Task numbers this one blocks / is blocked by. One relation, two views:
+   * Keys of tasks this one blocks / is blocked by. One relation, two views:
    * a single `(blocker, blocked)` row shows up in the blocker's `blocks` and
    * the blocked task's `blockedBy`, so the mirror can never drift.
    */
-  blocks: number[]
-  blockedBy: number[]
+  blocks: string[]
+  blockedBy: string[]
   /** Pull request URLs attached to this task. */
   prs: string[]
   /** Sort key within a status column; smaller sorts first. */
@@ -77,13 +114,13 @@ export interface ClaimsConfig {
 
 export interface ProjectConfig {
   name: string
-  /** Uppercase id prefix, e.g. "PHO" → PHO-1, PHO-2, … */
+  /** Uppercase id prefix, e.g. "PHO" → PHO-x7k4m, PHO-q3v8d, … */
   prefix: string
   version: number
   /**
-   * Pre-0.8 spelling of `claims.branchPrefix`, still read (the shared lock
-   * convention must not strand in-flight claims across a version bump).
-   * `task check` nags about it; `--fix` migrates it.
+   * Pre-0.8 spelling of `claims.branchPrefix`. Never honored — typed only so
+   * `claimNamespace` can refuse it by name instead of silently defaulting the
+   * board's committed lock convention out from under its workers.
    */
   claimPrefix?: string
   claims?: ClaimsConfig
@@ -131,7 +168,7 @@ export interface TaskFilter {
   /** Any-of: a task matches if it carries at least one of these tags. */
   tags?: string[]
   goal?: string
-  /** undefined = don't filter on it at all. */
+  /** Matches the *derived* flag — open asks, nothing else. undefined = don't filter. */
   needsHuman?: boolean
   /** true = list the archive instead of the board. */
   archived?: boolean
@@ -143,9 +180,8 @@ export interface TaskInput {
   status?: Status
   tags?: string[]
   goal?: string | null
-  needsHuman?: boolean
-  blocks?: number[]
-  blockedBy?: number[]
+  blocks?: string[]
+  blockedBy?: string[]
   prs?: string[]
 }
 
@@ -155,13 +191,12 @@ export interface TaskPatch {
   status?: Status
   tags?: string[]
   goal?: string | null
-  needsHuman?: boolean
   /**
    * Full replacement, like `tags` — the store reconciles the relation table
    * to match. Writing either side updates the other task's mirror view.
    */
-  blocks?: number[]
-  blockedBy?: number[]
+  blocks?: string[]
+  blockedBy?: string[]
   prs?: string[]
   /** Explicit board position (used by drag-and-drop in the UI). */
   position?: number