@nickmeriano/task 0.7.0 → 0.8.0

package/src/ticket-doc.ts

@@ -23,7 +23,8 @@ export interface TicketDoc {
   description: string
   status: Status
   tags: string[]
-  milestone: string | null
+  /** 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[]
@@ -31,8 +32,37 @@ export interface TicketDoc {
   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.
+ * `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.
+ */
+export const TICKET_FIELDS = [
+  "status",
+  "tags",
+  "goal",
+  "milestone",
+  "needs_human",
+  "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
@@ -64,13 +94,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 +116,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))
@@ -131,16 +170,16 @@ 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`)
+  const goal = field(raw, "goal") ?? field(raw, "milestone")
+  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")
@@ -151,18 +190,24 @@ 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,
+    goal: typeof goal === "string" && goal !== "" ? goal : null,
     needsHuman: needsHuman === true,
     blockedBy: numberList(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 +219,112 @@ 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.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}`)
   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 +339,76 @@ export function serializeComment(doc: CommentDoc): string {
   return `${lines.join("\n")}\n`
 }
 
+// ── 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 lenientNumbers(value: unknown): number[] {
+  return Array.isArray(value)
+    ? value.filter((v): v is number => typeof v === "number" && Number.isInteger(v))
+    : []
+}
+
+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")
+  // 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")
+  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,
+    needsHuman: field(raw, "needs_human") === true,
+    blockedBy: [...new Set(lenientNumbers(field(raw, "blocked_by")))].sort((a, b) => a - b),
+    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

@@ -17,7 +17,12 @@ export interface Task {
   description: string
   status: Status
   tags: string[]
-  milestone: string | null
+  /**
+   * 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
   /** This ticket can't be finished by an agent alone. */
   needsHuman: boolean
   /**
@@ -42,11 +47,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,26 +55,82 @@ export interface Comment {
   createdAt: string
 }
 
+/** 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. 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-1, PHO-2, … */
   prefix: string
   version: number
   /**
-   * 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.
+   * 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.
    */
   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
+  goal?: string
   /** undefined = don't filter on it at all. */
   needsHuman?: boolean
   /** true = list the archive instead of the board. */
@@ -85,7 +142,7 @@ export interface TaskInput {
   description?: string
   status?: Status
   tags?: string[]
-  milestone?: string | null
+  goal?: string | null
   needsHuman?: boolean
   blocks?: number[]
   blockedBy?: number[]
@@ -97,7 +154,7 @@ export interface TaskPatch {
   description?: string
   status?: Status
   tags?: string[]
-  milestone?: string | null
+  goal?: string | null
   needsHuman?: boolean
   /**
    * Full replacement, like `tags` — the store reconciles the relation table