@forgeailab/spark 0.2.0 → 0.3.0

package/src/internal/board.ts

@@ -1,4 +1,4 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
 export enum BoardTaskStatus {
@@ -6,6 +6,7 @@ export enum BoardTaskStatus {
   InProgress = 'in-progress',
   Done = 'done',
   Blocked = 'blocked',
+  Cut = 'cut',
 }
 
 export type BoardTask = {
@@ -41,221 +42,135 @@ export type SeedTask = {
   description?: string;
 };
 
-type DraftTask = {
-  kind: 'checkbox' | 'yaml';
-  id: string;
-  title: string;
-  status: BoardTaskStatus;
-  startIndex: number;
-};
-
-type DraftEpic = {
-  name: string;
-  startIndex: number;
-  firstTaskIndex?: number;
-  tasks: BoardTask[];
-};
+export type AggregatedTask = BoardTask & { changeId: string };
 
 const statusMarkers: Record<BoardTaskStatus, string> = {
   [BoardTaskStatus.Todo]: ' ',
   [BoardTaskStatus.InProgress]: '~',
   [BoardTaskStatus.Done]: 'x',
   [BoardTaskStatus.Blocked]: '!',
+  [BoardTaskStatus.Cut]: '-',
 };
 
-function boardFilePath(projectRoot: string): string {
-  return join(projectRoot, '.ai', 'board.md');
-}
-
 function cleanLine(line: string): string {
   return line.endsWith('\r') ? line.slice(0, -1) : line;
 }
 
 function boardLines(raw: string): string[] {
-  if (raw.length === 0) {
-    return [];
-  }
-
+  if (raw.length === 0) return [];
   return raw.endsWith('\n') ? raw.slice(0, -1).split('\n') : raw.split('\n');
 }
 
-function stripYamlValue(value: string): string {
-  const trimmed = value.trim();
-  if (
-    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
-    (trimmed.startsWith("'") && trimmed.endsWith("'"))
-  ) {
-    return trimmed.slice(1, -1);
-  }
-
-  return trimmed;
-}
-
-function parseKeyValue(line: string): { key: string; value: string } | undefined {
-  const index = line.indexOf(':');
-  if (index === -1) {
-    return undefined;
-  }
-
-  return {
-    key: line.slice(0, index).trim(),
-    value: stripYamlValue(line.slice(index + 1)),
-  };
-}
-
 function parseError(path: string, line: number, message: string): Error {
-  return new Error(`Malformed board at ${path}:${line}: ${message}`);
+  return new Error(`Malformed tasks file at ${path}:${line}: ${message}`);
 }
 
 function statusFromMarker(path: string, lineNumber: number, marker: string): BoardTaskStatus {
-  if (marker === ' ') {
-    return BoardTaskStatus.Todo;
-  }
-  if (marker === '~' || marker === '/') {
-    return BoardTaskStatus.InProgress;
-  }
-  if (marker === 'x' || marker === 'X') {
-    return BoardTaskStatus.Done;
-  }
-  if (marker === '!') {
-    return BoardTaskStatus.Blocked;
-  }
-
+  if (marker === ' ') return BoardTaskStatus.Todo;
+  if (marker === '~' || marker === '/') return BoardTaskStatus.InProgress;
+  if (marker === 'x' || marker === 'X') return BoardTaskStatus.Done;
+  if (marker === '!') return BoardTaskStatus.Blocked;
+  if (marker === '-') return BoardTaskStatus.Cut;
   throw parseError(path, lineNumber, `unsupported status marker "${marker}"`);
 }
 
-function statusFromValue(value: string): BoardTaskStatus | undefined {
-  const normalized = stripYamlValue(value).trim().toLowerCase().replace(/\s+/g, ' ');
-
-  if (
-    normalized === BoardTaskStatus.Todo ||
-    normalized === 'to do' ||
-    normalized === 'clarifying' ||
-    normalized === 'approved for planning'
-  ) {
-    return BoardTaskStatus.Todo;
-  }
-
-  if (
-    normalized === BoardTaskStatus.InProgress ||
-    normalized === 'in progress' ||
-    normalized === 'approved for execution' ||
-    normalized === 'needs review'
-  ) {
-    return BoardTaskStatus.InProgress;
-  }
-
-  if (normalized === BoardTaskStatus.Done || normalized === 'validated') {
-    return BoardTaskStatus.Done;
-  }
-
-  if (normalized === BoardTaskStatus.Blocked || normalized === 'cut from mvp') {
-    return BoardTaskStatus.Blocked;
-  }
-
-  return undefined;
-}
-
 function assertStatus(status: BoardTaskStatus, path: string): BoardTaskStatus {
-  if (Object.values(BoardTaskStatus).includes(status)) {
-    return status;
-  }
-
+  if ((Object.values(BoardTaskStatus) as string[]).includes(status)) return status;
   throw new Error(`Unsupported board task status "${status}" for ${path}`);
 }
 
-function parseCheckboxTask(path: string, lineNumber: number, line: string): DraftTask {
-  const match = /^\s*[-*]\s+\[([^\]])\]\s+([^\s:]+)\s*:\s*(.+?)\s*$/u.exec(line);
-  if (!match) {
-    throw parseError(path, lineNumber, 'expected checkbox task format "- [ ] TASK-ID: Title"');
-  }
-
-  return {
-    kind: 'checkbox',
-    id: match[2],
-    title: match[3],
-    status: statusFromMarker(path, lineNumber, match[1]),
-    startIndex: lineNumber - 1,
-  };
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-function parseYamlTaskStart(path: string, lineNumber: number, line: string): DraftTask {
-  const match = /^\s*-\s+id:\s*(.*)$/u.exec(line);
-  if (!match) {
-    throw parseError(path, lineNumber, 'expected YAML task id');
+/**
+ * Parse a task checkbox line. Supports two id styles:
+ *   - "- [ ] 1.2 Wire login form"    -> id="1.2",     title="Wire login form"
+ *   - "- [ ] PAY-001: Wire checkout" -> id="PAY-001", title="Wire checkout"
+ * Rule: id = first whitespace-delimited token after the checkbox, trailing ":" stripped.
+ * Side states may be a marker ([!]/[-]) or an inline annotation ("Blocked:"/"Cut:").
+ */
+function parseTaskLine(
+  path: string,
+  lineNumber: number,
+  line: string,
+): { id: string; title: string; status: BoardTaskStatus } | undefined {
+  const checkboxMatch = /^\s*[-*]\s+\[([^\]])\]\s+(.+)$/u.exec(line);
+  if (!checkboxMatch) return undefined;
+
+  const markerChar = checkboxMatch[1];
+  const rest = checkboxMatch[2].trim();
+  const spaceIdx = rest.search(/\s/u);
+
+  let id: string;
+  let title: string;
+  if (spaceIdx === -1) {
+    id = rest.replace(/:$/u, '');
+    title = id;
+  } else {
+    id = rest.slice(0, spaceIdx).replace(/:$/u, '');
+    title = rest.slice(spaceIdx).trim();
   }
 
-  const id = stripYamlValue(match[1]);
-  if (id.length === 0) {
-    throw parseError(path, lineNumber, 'task id is required');
+  if (id.length === 0) return undefined;
+
+  let status = statusFromMarker(path, lineNumber, markerChar);
+  // Documented founder form: side states annotated inline on a "- [ ]" line.
+  if (/(^|\s)Cut:/u.test(rest)) {
+    status = BoardTaskStatus.Cut;
+  } else if (status === BoardTaskStatus.Todo && /(^|\s)Blocked:/u.test(rest)) {
+    status = BoardTaskStatus.Blocked;
   }
 
-  return {
-    kind: 'yaml',
-    id,
-    title: id,
-    status: BoardTaskStatus.Todo,
-    startIndex: lineNumber - 1,
-  };
+  return { id, title, status };
 }
 
-function materializeTask(
-  path: string,
-  lines: readonly string[],
-  draft: DraftTask,
-  endIndex: number,
-): BoardTask {
-  const rawLines = lines.slice(draft.startIndex, endIndex);
-  let title = draft.title;
-  let status = draft.status;
-
-  if (draft.kind === 'yaml') {
-    for (const rawLine of rawLines.slice(1)) {
-      const kv = parseKeyValue(cleanLine(rawLine).trim());
-      if (!kv) {
-        continue;
-      }
-
-      if (kv.key === 'title') {
-        title = kv.value || title;
-      } else if (kv.key === 'status') {
-        const parsed = statusFromValue(kv.value);
-        if (!parsed) {
-          throw parseError(path, draft.startIndex + 1, `unsupported status "${kv.value}"`);
-        }
-        status = parsed;
-      }
-    }
+/** Returns the index of the first line AFTER a leading frontmatter block, else 0. */
+function skipFrontmatter(lines: readonly string[]): number {
+  if (lines.length === 0 || cleanLine(lines[0]).trim() !== '---') return 0;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (cleanLine(lines[i]).trim() === '---') return i + 1;
   }
-
-  return {
-    id: draft.id,
-    title,
-    status,
-    description: rawLines.slice(1).join('\n'),
-    raw: rawLines.join('\n'),
-    startLine: draft.startIndex + 1,
-    endLine: endIndex,
-  };
+  return 0;
 }
 
-function parseBoardMarkdown(path: string, raw: string): Board {
+type DraftTask = {
+  id: string;
+  title: string;
+  status: BoardTaskStatus;
+  startIndex: number;
+};
+
+type DraftEpic = {
+  name: string;
+  startIndex: number;
+  firstTaskIndex?: number;
+  tasks: BoardTask[];
+};
+
+export function parseTasksMarkdown(path: string, raw: string): Board {
   const lines = boardLines(raw);
   const epics: BoardEpic[] = [];
   const seenTaskIds = new Set<string>();
   let currentEpic: DraftEpic | undefined;
   let currentTask: DraftTask | undefined;
+  const startLine = skipFrontmatter(lines);
 
   function finishTask(endIndex: number): void {
-    if (!currentTask || !currentEpic) {
-      return;
-    }
-
-    const task = materializeTask(path, lines, currentTask, endIndex);
+    if (!currentTask || !currentEpic) return;
+    const rawLines = lines.slice(currentTask.startIndex, endIndex);
+    const task: BoardTask = {
+      id: currentTask.id,
+      title: currentTask.title,
+      status: currentTask.status,
+      description: rawLines.slice(1).join('\n'),
+      raw: rawLines.join('\n'),
+      startLine: currentTask.startIndex + 1,
+      endLine: endIndex,
+    };
     if (seenTaskIds.has(task.id)) {
       throw parseError(path, task.startLine, `duplicate task id "${task.id}"`);
     }
-
     seenTaskIds.add(task.id);
     currentEpic.firstTaskIndex ??= currentTask.startIndex;
     currentEpic.tasks.push(task);
@@ -263,10 +178,7 @@ function parseBoardMarkdown(path: string, raw: string): Board {
   }
 
   function finishEpic(endIndex: number): void {
-    if (!currentEpic) {
-      return;
-    }
-
+    if (!currentEpic) return;
     finishTask(endIndex);
     const descriptionEnd = currentEpic.firstTaskIndex ?? endIndex;
     epics.push({
@@ -280,39 +192,25 @@ function parseBoardMarkdown(path: string, raw: string): Board {
     currentEpic = undefined;
   }
 
-  for (let index = 0; index < lines.length; index += 1) {
+  for (let index = startLine; index < lines.length; index += 1) {
     const lineNumber = index + 1;
     const line = cleanLine(lines[index]);
+
     const epicMatch = /^##(?!#)\s+(.+?)\s*$/u.exec(line);
     if (epicMatch) {
       finishEpic(index);
-      currentEpic = {
-        name: epicMatch[1],
-        startIndex: index,
-        tasks: [],
-      };
-      continue;
-    }
-
-    const checkboxLike = /^\s*[-*]\s+\[[^\]]+\]\s+/u.test(line);
-    if (checkboxLike) {
-      if (!currentEpic) {
-        throw parseError(path, lineNumber, 'task appears before any epic heading');
-      }
-
-      finishTask(index);
-      currentTask = parseCheckboxTask(path, lineNumber, line);
+      currentEpic = { name: epicMatch[1], startIndex: index, tasks: [] };
       continue;
     }
 
-    const yamlTaskLike = /^\s*-\s+id:/u.test(line);
-    if (yamlTaskLike) {
+    if (/^\s*[-*]\s+\[[^\]]\]\s+/u.test(line)) {
       if (!currentEpic) {
-        throw parseError(path, lineNumber, 'task appears before any epic heading');
+        throw parseError(path, lineNumber, 'task appears before any section heading');
       }
-
       finishTask(index);
-      currentTask = parseYamlTaskStart(path, lineNumber, line);
+      const parsed = parseTaskLine(path, lineNumber, line);
+      if (!parsed) throw parseError(path, lineNumber, 'unrecognised task line format');
+      currentTask = { ...parsed, startIndex: index };
     }
   }
 
@@ -328,41 +226,103 @@ function parseBoardMarkdown(path: string, raw: string): Board {
   };
 }
 
-async function readExistingBoard(path: string): Promise<string> {
+// Legacy alias retained for any existing callers.
+export { parseTasksMarkdown as parseBoardMarkdown };
+
+// ---------------------------------------------------------------------------
+// Multi-change aggregation
+// ---------------------------------------------------------------------------
+
+export async function readAllChangeTasks(projectRoot: string): Promise<AggregatedTask[]> {
+  const changesDir = join(projectRoot, 'docs', 'spark', 'changes');
+  let changeIds: string[];
+
   try {
-    return await readFile(path, 'utf8');
+    const dirents = await readdir(changesDir, { withFileTypes: true });
+    changeIds = dirents
+      .filter((d) => d.isDirectory() && d.name !== 'archive')
+      .map((d) => d.name)
+      .sort();
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-      return '# Board\n';
-    }
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
     throw error;
   }
-}
 
-export async function readBoard(projectRoot: string): Promise<Board> {
-  const path = boardFilePath(projectRoot);
+  const allTasks: AggregatedTask[] = [];
 
-  try {
-    const raw = await readFile(path, 'utf8');
-    return parseBoardMarkdown(path, raw);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-      throw new Error(`Board file not found at ${path}`, { cause: error });
+  for (const changeId of changeIds) {
+    const tasksPath = join(changesDir, changeId, 'tasks.md');
+    let raw: string;
+    try {
+      raw = await readFile(tasksPath, 'utf8');
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+      throw error;
+    }
+    const board = parseTasksMarkdown(tasksPath, raw);
+    for (const epic of board.epics) {
+      for (const task of epic.tasks) {
+        allTasks.push({ ...task, changeId });
+      }
     }
-    throw error;
   }
+
+  return allTasks;
 }
 
-function escapeRegex(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// ---------------------------------------------------------------------------
+// renderBuildStatus — pure, deterministic
+// ---------------------------------------------------------------------------
+
+export function renderBuildStatus(tasks: readonly AggregatedTask[]): string {
+  const todo = tasks.filter((t) => t.status === BoardTaskStatus.Todo);
+  const inProgress = tasks.filter((t) => t.status === BoardTaskStatus.InProgress);
+  const done = tasks.filter((t) => t.status === BoardTaskStatus.Done);
+  const blocked = tasks.filter((t) => t.status === BoardTaskStatus.Blocked);
+  const cut = tasks.filter((t) => t.status === BoardTaskStatus.Cut);
+
+  const lines: string[] = [
+    `Todo: ${todo.length} · In progress: ${inProgress.length} · Done: ${done.length} · Blocked: ${blocked.length}`,
+  ];
+
+  function renderGroup(label: string, group: readonly AggregatedTask[]): void {
+    if (group.length === 0) return;
+    lines.push(`\n### ${label}`);
+    const sorted = [...group].sort((a, b) =>
+      a.changeId === b.changeId ? a.id.localeCompare(b.id) : a.changeId.localeCompare(b.changeId),
+    );
+    for (const task of sorted) {
+      lines.push(`- [${task.changeId}] ${task.id}: ${task.title}`);
+    }
+  }
+
+  renderGroup('In progress', inProgress);
+  renderGroup('Blocked', blocked);
+  renderGroup('Todo', todo);
+  renderGroup('Done', done);
+  if (cut.length > 0) renderGroup('Cut', cut);
+
+  return lines.join('\n');
 }
 
-function boardHasTask(board: string, taskId: string): boolean {
-  const escaped = escapeRegex(taskId);
-  const checkboxPattern = new RegExp(`(^|\\n)\\s*[-*]\\s+\\[[^\\]]+\\]\\s+${escaped}\\s*:`, 'u');
-  const yamlPattern = new RegExp(`(^|\\n)\\s*-\\s+id:\\s*["']?${escaped}["']?\\s*(\\n|$)`, 'u');
+// ---------------------------------------------------------------------------
+// Pack-install task seeding
+// ---------------------------------------------------------------------------
+
+export function packInstallChangeId(date: Date = new Date()): string {
+  const yyyy = date.getUTCFullYear();
+  const mm = String(date.getUTCMonth() + 1).padStart(2, '0');
+  const dd = String(date.getUTCDate()).padStart(2, '0');
+  return `pack-install-${yyyy}-${mm}-${dd}`;
+}
+
+function changeTasksFilePath(projectRoot: string, changeId: string): string {
+  return join(projectRoot, 'docs', 'spark', 'changes', changeId, 'tasks.md');
+}
 
-  return checkboxPattern.test(board) || yamlPattern.test(board);
+function buildFrontmatter(): string {
+  const now = new Date().toISOString();
+  return `---\ncreated_at: ${now}\nupdated_at: ${now}\ncompleted_at:\n---\n`;
 }
 
 function generatedTaskId(packName: string, index: number): string {
@@ -370,7 +330,6 @@ function generatedTaskId(packName: string, index: number): string {
     .toUpperCase()
     .replace(/[^A-Z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '');
-
   return `${prefix || 'PACK'}-${String(index + 1).padStart(3, '0')}`;
 }
 
@@ -383,7 +342,6 @@ function normalizeSeedTask(
   if (task.title.trim().length === 0) {
     throw new Error(`Cannot seed board task with an empty title for ${path}`);
   }
-
   return {
     id: task.id?.trim() || generatedTaskId(packName, index),
     title: task.title.trim(),
@@ -392,69 +350,69 @@ function normalizeSeedTask(
   };
 }
 
-function formatSeedTask(task: Required<SeedTask>): string {
+function formatSeedTask(task: Required<SeedTask>, packName: string): string {
   const lines = [`- [${statusMarkers[task.status]}] ${task.id}: ${task.title}`];
+  lines.push('  - Status: Clarifying');
+  lines.push(`  - requires_pack: ${packName}`);
   const description = task.description.replace(/\r\n/g, '\n').replace(/\n$/u, '');
-
   if (description.trim().length > 0) {
-    lines.push(...description.split('\n').map((line) => `  ${line}`));
+    lines.push(...description.split('\n').map((l) => `  ${l}`));
   }
-
   return lines.join('\n');
 }
 
-function lineStartOffsets(raw: string): number[] {
-  const offsets = [0];
-  for (let index = 0; index < raw.length; index += 1) {
-    if (raw[index] === '\n') {
-      offsets.push(index + 1);
-    }
-  }
+function rawHasTaskId(raw: string, taskId: string): boolean {
+  const escaped = escapeRegex(taskId);
+  return new RegExp(`(^|\\n)\\s*[-*]\\s+\\[[^\\]]\\]\\s+${escaped}(?::|\\s|$)`, 'u').test(raw);
+}
 
-  return offsets;
+async function readExistingRaw(path: string): Promise<string> {
+  try {
+    return await readFile(path, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return '';
+    throw error;
+  }
 }
 
-function findSectionInsertIndex(board: string, packName: string): number | undefined {
+function appendPackSection(
+  raw: string,
+  packName: string,
+  tasks: readonly Required<SeedTask>[],
+): string {
+  const taskBlock = tasks.map((t) => formatSeedTask(t, packName)).join('\n\n');
   const heading = `## ${packName}`;
-  const lines = board.split('\n');
-  const offsets = lineStartOffsets(board);
+  const rawLines = raw.split('\n');
   let headingIndex = -1;
 
-  for (let index = 0; index < lines.length; index += 1) {
-    if (cleanLine(lines[index]).trim() === heading) {
-      headingIndex = index;
+  for (let i = 0; i < rawLines.length; i += 1) {
+    if (cleanLine(rawLines[i]).trim() === heading) {
+      headingIndex = i;
       break;
     }
   }
 
   if (headingIndex === -1) {
-    return undefined;
+    const sep = raw.endsWith('\n') ? '\n' : '\n\n';
+    return `${raw}${sep}${heading}\n\n${taskBlock}\n`;
   }
 
-  for (let index = headingIndex + 1; index < lines.length; index += 1) {
-    if (/^##(?!#)\s+/u.test(cleanLine(lines[index]))) {
-      return offsets[index] ?? board.length;
+  // Section exists — insert before the next "## " heading, or at EOF.
+  let insertOffset = raw.length;
+  let charCount = 0;
+  for (let i = 0; i < rawLines.length; i += 1) {
+    if (i > headingIndex && /^##(?!#)\s+/u.test(cleanLine(rawLines[i]))) {
+      insertOffset = charCount;
+      break;
     }
+    charCount += rawLines[i].length + 1;
   }
 
-  return board.length;
-}
-
-function appendTasks(board: string, packName: string, tasks: readonly Required<SeedTask>[]): string {
-  const taskBlock = tasks.map(formatSeedTask).join('\n\n');
-  const insertIndex = findSectionInsertIndex(board, packName);
-
-  if (insertIndex === undefined) {
-    const separator = board.endsWith('\n') ? '\n' : '\n\n';
-    return `${board}${separator}## ${packName}\n\n${taskBlock}\n`;
-  }
-
-  const before = board.slice(0, insertIndex);
-  const after = board.slice(insertIndex);
-  const separator = before.endsWith('\n\n') ? '' : before.endsWith('\n') ? '\n' : '\n\n';
-  const afterSeparator = after.length > 0 ? '\n' : '';
-
-  return `${before}${separator}${taskBlock}\n${afterSeparator}${after}`;
+  const before = raw.slice(0, insertOffset);
+  const after = raw.slice(insertOffset);
+  const sep = before.endsWith('\n\n') ? '' : before.endsWith('\n') ? '\n' : '\n\n';
+  const afterSep = after.length > 0 ? '\n' : '';
+  return `${before}${sep}${taskBlock}\n${afterSep}${after}`;
 }
 
 export async function seedTasks(
@@ -462,36 +420,40 @@ export async function seedTasks(
   packName: string,
   tasks: Array<SeedTask>,
 ): Promise<void> {
-  if (tasks.length === 0) {
-    return;
-  }
+  if (tasks.length === 0) return;
+
+  const existingIds = new Set((await readAllChangeTasks(projectRoot)).map((t) => t.id));
+  const path = changeTasksFilePath(projectRoot, packInstallChangeId());
+  const currentRaw = await readExistingRaw(path);
 
-  const path = boardFilePath(projectRoot);
-  const board = await readExistingBoard(path);
   const normalizedTasks = tasks
     .map((task, index) => normalizeSeedTask(path, packName, task, index))
-    .filter((task) => !boardHasTask(board, task.id));
+    .filter((task) => !existingIds.has(task.id) && !rawHasTaskId(currentRaw, task.id));
 
-  if (normalizedTasks.length === 0) {
-    return;
-  }
+  if (normalizedTasks.length === 0) return;
+
+  const base = currentRaw.length > 0 ? currentRaw : buildFrontmatter();
+  const next = appendPackSection(base, packName, normalizedTasks);
 
   await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, appendTasks(board, packName, normalizedTasks));
+  await writeFile(path, next);
 }
 
+// ---------------------------------------------------------------------------
+// updateStatus — parameterized by the tasks file path
+// ---------------------------------------------------------------------------
+
 export async function updateStatus(
-  projectRoot: string,
+  tasksFile: string,
   taskId: string,
   status: BoardTaskStatus,
 ): Promise<void> {
-  const path = boardFilePath(projectRoot);
-  const nextStatus = assertStatus(status, path);
-  const raw = await readFile(path, 'utf8');
+  const nextStatus = assertStatus(status, tasksFile);
+  const raw = await readFile(tasksFile, 'utf8');
   const lines = raw.split('\n');
   const marker = statusMarkers[nextStatus];
   const checkboxPattern = new RegExp(
-    `^(\\s*[-*]\\s+\\[)([^\\]])(\\]\\s+${escapeRegex(taskId)}\\s*:\\s*.+)$`,
+    `^(\\s*[-*]\\s+\\[)([^\\]])(\\]\\s+${escapeRegex(taskId)}(?::|\\s).*)$`,
     'u',
   );
 
@@ -499,43 +461,43 @@ export async function updateStatus(
     const originalLine = lines[index];
     const hasCarriage = originalLine.endsWith('\r');
     const line = cleanLine(originalLine);
-    const checkboxMatch = checkboxPattern.exec(line);
-
-    if (checkboxMatch) {
-      lines[index] = `${checkboxMatch[1]}${marker}${checkboxMatch[3]}${hasCarriage ? '\r' : ''}`;
+    const match = checkboxPattern.exec(line);
+    if (match) {
+      lines[index] = `${match[1]}${marker}${match[3]}${hasCarriage ? '\r' : ''}`;
       const nextRaw = lines.join('\n');
-      if (nextRaw !== raw) {
-        await writeFile(path, nextRaw);
-      }
+      if (nextRaw !== raw) await writeFile(tasksFile, nextRaw);
       return;
     }
+  }
 
-    const yamlMatch = /^\s*-\s+id:\s*(.*)$/u.exec(line);
-    if (yamlMatch && stripYamlValue(yamlMatch[1]) === taskId) {
-      for (let nextIndex = index + 1; nextIndex < lines.length; nextIndex += 1) {
-        const candidate = cleanLine(lines[nextIndex]);
-        if (/^##(?!#)\s+/u.test(candidate) || /^\s*-\s+id:/u.test(candidate)) {
-          break;
-        }
-
-        const statusMatch = /^(\s*status:\s*)(.*?)(\s*)$/u.exec(candidate);
-        if (!statusMatch) {
-          continue;
-        }
-
-        const candidateHasCarriage = lines[nextIndex].endsWith('\r');
-        lines[nextIndex] =
-          `${statusMatch[1]}${nextStatus}${statusMatch[3]}${candidateHasCarriage ? '\r' : ''}`;
-        const nextRaw = lines.join('\n');
-        if (nextRaw !== raw) {
-          await writeFile(path, nextRaw);
-        }
-        return;
-      }
+  throw new Error(`Task "${taskId}" not found in ${tasksFile}`);
+}
 
-      throw new Error(`Task "${taskId}" has no status marker in ${path}`);
+// ---------------------------------------------------------------------------
+// readBoard — reads a single change's tasks.md, or aggregates across changes
+// ---------------------------------------------------------------------------
+
+export async function readBoard(projectRoot: string, changeId?: string): Promise<Board> {
+  if (changeId) {
+    const path = changeTasksFilePath(projectRoot, changeId);
+    try {
+      const raw = await readFile(path, 'utf8');
+      return parseTasksMarkdown(path, raw);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        throw new Error(`Tasks file not found at ${path}`, { cause: error });
+      }
+      throw error;
     }
   }
 
-  throw new Error(`Task "${taskId}" not found in ${path}`);
+  const allTasks = await readAllChangeTasks(projectRoot);
+  return {
+    path: join(projectRoot, 'docs', 'spark', 'changes'),
+    raw: '',
+    epics: [],
+    toMarkdown() {
+      return renderBuildStatus(allTasks);
+    },
+  };
 }