@nickmeriano/task 0.7.1 → 0.9.0

package/src/ticket-doc.ts

@@ -23,22 +23,60 @@ export interface TicketDoc {
   description: string
   status: Status
   tags: string[]
-  milestone: string | null
-  needsHuman: boolean
-  /** Task numbers blocking this one — the single stored side of the relation. */
-  blockedBy: number[]
+  /** Slug of the goal this ticket belongs to — at most one, by design. */
+  goal: string | null
+  /** Keys of tasks blocking this one — the single stored side of the relation. */
+  blockedBy: string[]
   prs: string[]
   position: number
   createdAt: string
   updatedAt: string
+  /**
+   * Frontmatter keys this version doesn't know, as raw `[key, value]` pairs in
+   * file order. Carried so a rewrite can't silently drop them — a hand-added
+   * field (or one written by a newer CLI) survives every update, re-emitted
+   * after the known fields. Present only when the file actually has any.
+   */
+  extras?: [string, string][]
 }
 
+/** The frontmatter keys a ticket file may carry; anything else is an extra. */
+export const TICKET_FIELDS = [
+  "status",
+  "tags",
+  "goal",
+  "blocked_by",
+  "prs",
+  "position",
+  "created",
+  "updated",
+] as const
+
+/** The frontmatter keys a comment file may carry. */
+export const COMMENT_FIELDS = ["author", "created"] as const
+
 export interface CommentDoc {
   author: string
   createdAt: string
   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 {}
 
@@ -64,13 +102,21 @@ function parseScalar(raw: string): unknown {
   }
 }
 
-function splitRaw(text: string, where: string): RawDoc {
+/**
+ * Split a file into frontmatter fields and body. Two callers, two stances:
+ * with a `where` the CLI is parsing and every malformation throws, naming the
+ * file; with `where: null` the hosted board is rendering and a file with no
+ * frontmatter returns null while a merely-odd line is skipped.
+ */
+function splitRaw(text: string, where: string | null): RawDoc | null {
   const lines = text.replace(/\r\n/g, "\n").split("\n")
   if (lines[0] !== "---") {
+    if (where === null) return null
     throw new TicketParseError(`${where}: expected the file to start with a --- frontmatter block`)
   }
   const end = lines.indexOf("---", 1)
   if (end < 0) {
+    if (where === null) return null
     throw new TicketParseError(`${where}: unterminated frontmatter — no closing ---`)
   }
   const fields = new Map<string, string>()
@@ -78,6 +124,7 @@ function splitRaw(text: string, where: string): RawDoc {
     if (!line.trim()) continue
     const colon = line.indexOf(":")
     if (colon < 0) {
+      if (where === null) continue
       throw new TicketParseError(`${where}: not a "key: value" frontmatter line: ${line}`)
     }
     fields.set(line.slice(0, colon).trim(), line.slice(colon + 1))
@@ -105,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 ──────────────────────────────────────────────────────────────────
@@ -131,18 +182,25 @@ function splitTitle(body: string): { title: string | null; description: string }
 }
 
 export function parseTicket(text: string, where: string): TicketDoc {
-  const raw = splitRaw(text, where)
+  const raw = splitRaw(text, where)!
   const status = stringField(raw, "status", where, "todo")
   if (!isStatus(status)) {
     throw new TicketParseError(
       `${where}: invalid status "${status}" — one of: ${STATUSES.join(", ")}`,
     )
   }
-  const milestone = field(raw, "milestone")
-  if (milestone !== undefined && milestone !== null && typeof milestone !== "string") {
-    throw new TicketParseError(`${where}: milestone should be a string`)
+  // 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`)
@@ -151,18 +209,23 @@ export function parseTicket(text: string, where: string): TicketDoc {
   if (title === null) {
     throw new TicketParseError(`${where}: expected the body to start with "# <title>"`)
   }
+  const known = new Set<string>(TICKET_FIELDS)
+  const extras: [string, string][] = []
+  for (const [key, value] of raw.fields) {
+    if (!known.has(key)) extras.push([key, value.trim()])
+  }
   return {
     title,
     description,
     status,
     tags: stringList(raw, "tags", where),
-    milestone: typeof milestone === "string" && milestone !== "" ? milestone : null,
-    needsHuman: needsHuman === true,
-    blockedBy: numberList(raw, "blocked_by", where),
+    goal: typeof goal === "string" && goal !== "" ? goal : null,
+    blockedBy: keyList(raw, "blocked_by", where),
     prs: stringList(raw, "prs", where),
     position: typeof position === "number" ? position : 0,
     createdAt: stringField(raw, "created", where, ""),
     updatedAt: stringField(raw, "updated", where, ""),
+    ...(extras.length ? { extras } : {}),
   }
 }
 
@@ -174,27 +237,111 @@ function list(values: (string | number)[]): string {
 /**
  * The canonical bytes for a ticket. Field order is fixed and empty fields are
  * omitted, so an unchanged ticket always serializes identically — diffs show
- * edits, never churn.
+ * edits, never churn. Unknown fields the parse carried through are re-emitted
+ * after the known ones, in their original order.
  */
 export function serializeTicket(doc: TicketDoc): string {
   const lines = ["---", `status: ${doc.status}`]
   if (doc.tags.length) lines.push(`tags: ${list(doc.tags)}`)
-  if (doc.milestone) lines.push(`milestone: ${JSON.stringify(doc.milestone)}`)
-  if (doc.needsHuman) lines.push(`needs_human: true`)
+  if (doc.goal) lines.push(`goal: ${JSON.stringify(doc.goal)}`)
   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}`)
   lines.push(`created: ${doc.createdAt}`)
   lines.push(`updated: ${doc.updatedAt}`)
+  for (const [key, value] of doc.extras ?? []) lines.push(`${key}: ${value}`)
+  lines.push("---", "", `# ${doc.title}`)
+  if (doc.description) lines.push("", doc.description)
+  return `${lines.join("\n")}\n`
+}
+
+// ── Goals ────────────────────────────────────────────────────────────────────
+//
+// A goal is one file — `.task/goals/<slug>.md` — in the ticket format minus
+// the workflow fields: no status (progress is derived from its tasks), no
+// position (goals aren't a column). The slug is the filename stem and the
+// identity tickets reference via `goal:`; the title inside can change freely.
+
+/** Everything `goals/<slug>.md` stores. The slug is the filename, not a field. */
+export interface GoalDoc {
+  title: string
+  description: string
+  createdAt: string
+  updatedAt: string
+  /** Unknown frontmatter, carried through rewrites — same deal as tickets. */
+  extras?: [string, string][]
+}
+
+/** The frontmatter keys a goal file may carry. */
+export const GOAL_FIELDS = ["created", "updated"] as const
+
+/**
+ * What a goal slug may look like — same alphabet as the claim-branch-safe
+ * ticket ids, because the slug ends up in frontmatter, URLs and prompts.
+ * "archive" is reserved: `goals/archive/` is where archived goals live.
+ */
+export const GOAL_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/
+
+export function isGoalSlug(value: string): boolean {
+  return GOAL_SLUG_PATTERN.test(value) && value !== "archive"
+}
+
+/** Derive a slug from a title: "Trust & guardrail layer" → "trust-guardrail-layer". */
+export function slugifyGoal(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64)
+    .replace(/-+$/g, "")
+}
+
+export function parseGoal(text: string, where: string): GoalDoc {
+  const raw = splitRaw(text, where)!
+  const { title, description } = splitTitle(raw.body)
+  if (title === null) {
+    throw new TicketParseError(`${where}: expected the body to start with "# <title>"`)
+  }
+  const known = new Set<string>(GOAL_FIELDS)
+  const extras: [string, string][] = []
+  for (const [key, value] of raw.fields) {
+    if (!known.has(key)) extras.push([key, value.trim()])
+  }
+  return {
+    title,
+    description,
+    createdAt: stringField(raw, "created", where, ""),
+    updatedAt: stringField(raw, "updated", where, ""),
+    ...(extras.length ? { extras } : {}),
+  }
+}
+
+/** Canonical bytes for a goal — fixed field order, like tickets. */
+export function serializeGoal(doc: GoalDoc): string {
+  const lines = ["---", `created: ${doc.createdAt}`, `updated: ${doc.updatedAt}`]
+  for (const [key, value] of doc.extras ?? []) lines.push(`${key}: ${value}`)
   lines.push("---", "", `# ${doc.title}`)
   if (doc.description) lines.push("", doc.description)
   return `${lines.join("\n")}\n`
 }
 
+/** A goal, forgivingly — null when there's no frontmatter at all. */
+export function parseGoalLenient(text: string): GoalDoc | null {
+  const raw = splitRaw(text, null)
+  if (!raw) return null
+  const { title, description } = splitTitle(raw.body)
+  return {
+    title: title ?? "",
+    description,
+    createdAt: lenientString(field(raw, "created")),
+    updatedAt: lenientString(field(raw, "updated")),
+  }
+}
+
 // ── Comments ─────────────────────────────────────────────────────────────────
 
 export function parseComment(text: string, where: string): CommentDoc {
-  const raw = splitRaw(text, where)
+  const raw = splitRaw(text, where)!
   return {
     author: stringField(raw, "author", where, ""),
     createdAt: stringField(raw, "created", where, ""),
@@ -209,6 +356,122 @@ 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
+// file, so a malformation is a bug worth halting on — but a renderer is looking
+// at whatever a hand-edit or a bad merge left behind, and it must degrade
+// rather than throw: a broken ticket becomes a degraded ticket (unknown status
+// → backlog, missing heading → empty title), never a broken board. Living here
+// rather than restated in the worker keeps one definition of the format.
+
+function lenientStrings(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((v): v is string => typeof v === "string") : []
+}
+
+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 {
+  return typeof value === "string" ? value : ""
+}
+
+/** A ticket, forgivingly — or null when there's no frontmatter to read at all. */
+export function parseTicketLenient(text: string): TicketDoc | null {
+  const raw = splitRaw(text, null)
+  if (!raw) return null
+  const status = field(raw, "status")
+  // 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 {
+    title: title ?? "",
+    description,
+    status: typeof status === "string" && isStatus(status) ? status : "backlog",
+    tags: lenientStrings(field(raw, "tags")),
+    goal: typeof goal === "string" && goal !== "" ? goal : null,
+    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")),
+    updatedAt: lenientString(field(raw, "updated")),
+  }
+}
+
+/**
+ * The frontmatter keys a file carries, leniently — null when there's no
+ * frontmatter at all. `task check` uses this to spot unknown keys in files
+ * whose parsed shape (comments) doesn't carry them through.
+ */
+export function frontmatterKeys(text: string): string[] | null {
+  const raw = splitRaw(text, null)
+  return raw ? [...raw.fields.keys()] : null
+}
+
+/** A comment, forgivingly — or null when there's no frontmatter at all. */
+export function parseCommentLenient(text: string): CommentDoc | null {
+  const raw = splitRaw(text, null)
+  if (!raw) return null
+  return {
+    author: lenientString(field(raw, "author")),
+    createdAt: lenientString(field(raw, "created")),
+    body: raw.body,
+  }
+}
+
 /**
  * A comment's filename stem — readable, sortable, and unique enough that two
  * branches almost never mint the same one: `2026-08-15T165943-claude`. The

package/src/types.ts

@@ -9,24 +9,66 @@ 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
   tags: string[]
-  milestone: string | null
-  /** This ticket can't be finished by an agent alone. */
+  /**
+   * Slug of the goal this task belongs to — at most one. Tags answer "what
+   * kind" (many); the goal answers "where is this going" (one). Something that
+   * wants to live in two goals is a tag.
+   */
+  goal: string | null
+  /**
+   * 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. */
@@ -42,11 +84,7 @@ export interface Task {
 }
 
 export interface Comment {
-  /**
-   * Stable opaque id. On file-backed boards it's the comment's filename stem
-   * (e.g. "2026-08-15T165943-claude"); on legacy SQLite boards, the rowid as a
-   * string.
-   */
+  /** Stable opaque id — the comment's filename stem (e.g. "2026-08-15T165943-claude"). */
   id: string
   taskId: string
   author: string
@@ -54,27 +92,83 @@ export interface Comment {
   createdAt: string
 }
 
-export interface ProjectConfig {
-  name: string
-  /** Uppercase id prefix, e.g. "PHO" → PHO-1, PHO-2, … */
-  prefix: string
-  version: number
+/** How this board's tickets get claimed — see `claim.ts` for the mechanics. */
+export interface ClaimsConfig {
   /**
    * Branch namespace `task claim` creates claim branches under — committed
    * with the board on purpose, so every worker and every clone agree on what
    * "claimed" looks like. Defaults to "task/claim/"; repos whose workers are
    * Claude Code cloud sessions set "claude/task/", the one prefix that
-   * runtime can push without extra ceremony.
+   * runtime can push without extra ceremony. Must agree across a repo's
+   * boards (`task check` lints it) — workflows match claim branches by
+   * pattern, and one repo with two patterns matches neither reliably.
+   */
+  branchPrefix?: string
+  /**
+   * Repo-wide cap on open claims: `task claim` refuses (exit 2) while this
+   * many claim branches exist on origin, `--force` overrides. Read from the
+   * repo's *root* board only — a WIP cap per board is no cap at all.
+   */
+  maxOpenCount?: number
+}
+
+export interface ProjectConfig {
+  name: string
+  /** Uppercase id prefix, e.g. "PHO" → PHO-x7k4m, PHO-q3v8d, … */
+  prefix: string
+  version: number
+  /**
+   * 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
+  /**
+   * Root board only: the repo's automation-visible boards, by id prefix, in
+   * priority order. This is *selection scope* — where `claim --next` and
+   * `list --claimable` look — not permission: explicit-id claims work on any
+   * board regardless. Absent → automation sees the nearest board only, so a
+   * vendored board can't opt itself in.
+   */
+  boards?: string[]
+}
+
+/**
+ * A goal: a titled, described destination that tasks belong to. Progress is
+ * always derived from its tasks — a goal has no stored status on purpose,
+ * because a second state machine is a second thing that can lie.
+ */
+export interface Goal {
+  /** Filename stem under `.task/goals/` — the stable identity tickets reference. */
+  slug: string
+  title: string
+  /** The strategic why. Tickets keep the how; this is the context they share. */
+  description: string
+  createdAt: string
+  updatedAt: string
+  /** Set (to true) only on goals living in `.task/goals/archive/`. */
+  archived?: boolean
+}
+
+export interface GoalInput {
+  title: string
+  /** Derived from the title when omitted. */
+  slug?: string
+  description?: string
+}
+
+export interface GoalPatch {
+  title?: string
+  description?: string
 }
 
 export interface TaskFilter {
   statuses?: Status[]
   /** Any-of: a task matches if it carries at least one of these tags. */
   tags?: string[]
-  milestone?: string
-  /** undefined = don't filter on it at all. */
+  goal?: string
+  /** Matches the *derived* flag — open asks, nothing else. undefined = don't filter. */
   needsHuman?: boolean
   /** true = list the archive instead of the board. */
   archived?: boolean
@@ -85,10 +179,9 @@ export interface TaskInput {
   description?: string
   status?: Status
   tags?: string[]
-  milestone?: string | null
-  needsHuman?: boolean
-  blocks?: number[]
-  blockedBy?: number[]
+  goal?: string | null
+  blocks?: string[]
+  blockedBy?: string[]
   prs?: string[]
 }
 
@@ -97,14 +190,13 @@ export interface TaskPatch {
   description?: string
   status?: Status
   tags?: string[]
-  milestone?: string | null
-  needsHuman?: boolean
+  goal?: string | null
   /**
    * 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