mstro-app 0.4.2 → 0.4.3

package/server/services/plan/front-matter.ts

@@ -0,0 +1,48 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Front Matter Utilities — Read/write YAML front matter fields.
+ *
+ * All replacements are scoped to the --- delimiters to prevent
+ * markdown body corruption. Used across executor, plan-handlers,
+ * and state-reconciler.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+
+/**
+ * Replace a field value in a raw YAML string (no --- delimiters).
+ * If the field does not exist, it is appended.
+ */
+export function replaceYamlField(yaml: string, field: string, value: string): string {
+  const regex = new RegExp(`^(${field}:\\s*).+$`, 'm');
+  if (regex.test(yaml)) {
+    return yaml.replace(regex, `$1${value}`);
+  }
+  return `${yaml}\n${field}: ${value}`;
+}
+
+/**
+ * Replace a YAML front matter field in a full markdown content string.
+ * Only modifies content between the first pair of --- delimiters.
+ * If the field does not exist in front matter, it is appended.
+ * Returns content unchanged if no front matter block is found.
+ */
+export function replaceFrontMatterField(content: string, field: string, value: string): string {
+  const fmMatch = content.match(/^(---\n)([\s\S]*?)(\n---)/);
+  if (!fmMatch) return content;
+
+  const yaml = replaceYamlField(fmMatch[2], field, value);
+  return `${fmMatch[1]}${yaml}${fmMatch[3]}${content.slice(fmMatch[0].length)}`;
+}
+
+/**
+ * Read a file, update a front matter field, and write it back.
+ * Convenience wrapper for single-field updates.
+ */
+export function setFrontMatterField(filePath: string, field: string, value: string): void {
+  const content = readFileSync(filePath, 'utf-8');
+  const updated = replaceFrontMatterField(content, field, value);
+  writeFileSync(filePath, updated, 'utf-8');
+}

package/server/services/plan/output-manager.ts

@@ -0,0 +1,113 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Output Manager — Resolves output paths, lists existing docs, and publishes outputs.
+ *
+ * Handles sprint-sandboxed and global output directories with fallback.
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { defaultPmDir, resolvePmDir } from './parser.js';
+import type { Issue } from './types.js';
+
+/** Convert a title to a URL-friendly slug (max 60 chars). */
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+}
+
+/**
+ * Resolve the canonical output path for an issue.
+ * Uses sprint sandbox when available, otherwise global .pm/out/.
+ */
+export function resolveOutputPath(issue: Issue, workingDir: string, sprintSandboxDir: string | null): string {
+  if (sprintSandboxDir) {
+    return join(sprintSandboxDir, 'out', `${issue.id}-${slugify(issue.title)}.md`);
+  }
+  const pmDir = resolvePmDir(workingDir);
+  const outDir = pmDir ? join(pmDir, 'out') : join(defaultPmDir(workingDir), 'out');
+  return join(outDir, `${issue.id}-${slugify(issue.title)}.md`);
+}
+
+/**
+ * List existing execution output docs.
+ * Searches sprint sandbox first (higher priority), then global out/.
+ */
+export function listExistingDocs(workingDir: string, sprintSandboxDir: string | null): string[] {
+  const pmDir = resolvePmDir(workingDir);
+  if (!pmDir) return [];
+
+  const dirs: string[] = [];
+  if (sprintSandboxDir) dirs.push(join(sprintSandboxDir, 'out'));
+  dirs.push(join(pmDir, 'out'));
+
+  const docs: string[] = [];
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    try {
+      docs.push(...readdirSync(dir).filter(f => f.endsWith('.md')).map(f => join(dir, f)));
+    } catch { /* skip */ }
+  }
+  return docs;
+}
+
+export interface PublishOutputsCallbacks {
+  onWarning?: (issueId: string, text: string) => void;
+}
+
+/**
+ * Copy confirmed-done outputs from .pm/out/ to user-specified output_file paths.
+ * Only copies for issues that completed successfully and have output_file set.
+ */
+export function publishOutputs(
+  issues: Issue[],
+  workingDir: string,
+  sprintSandboxDir: string | null,
+  callbacks?: PublishOutputsCallbacks,
+): void {
+  const pmDir = resolvePmDir(workingDir);
+  if (!pmDir) return;
+
+  for (const issue of issues) {
+    publishSingleOutput(issue, pmDir, workingDir, sprintSandboxDir, callbacks);
+  }
+}
+
+function publishSingleOutput(
+  issue: Issue,
+  pmDir: string,
+  workingDir: string,
+  sprintSandboxDir: string | null,
+  callbacks?: PublishOutputsCallbacks,
+): void {
+  if (!issue.outputFile) return;
+
+  // Only publish for confirmed-done issues
+  try {
+    const content = readFileSync(join(pmDir, issue.path), 'utf-8');
+    if (!content.match(/^status:\s*done$/m)) return;
+  } catch { return; }
+
+  const srcPath = resolveOutputPath(issue, workingDir, sprintSandboxDir);
+  if (!existsSync(srcPath)) return;
+
+  // Guard against path traversal — output_file must resolve within workingDir
+  const destPath = resolve(workingDir, issue.outputFile);
+  if (!destPath.startsWith(`${workingDir}/`) && destPath !== workingDir) {
+    callbacks?.onWarning?.(issue.id, `output_file "${issue.outputFile}" escapes project directory — skipping`);
+    return;
+  }
+
+  try {
+    const destDir = join(destPath, '..');
+    if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
+    copyFileSync(srcPath, destPath);
+  } catch {
+    callbacks?.onWarning?.(issue.id, `could not copy output to ${issue.outputFile}`);
+  }
+}

package/server/services/plan/parser.ts

@@ -7,10 +7,14 @@
  * Handles YAML front matter extraction and markdown body parsing.
  */
 
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type {
   AcceptanceCriterion,
+  Board,
+  BoardArtifacts,
+  BoardExecutionSummary,
+  BoardFullState,
   Issue,
   IssueSummary,
   Milestone,
@@ -18,10 +22,14 @@ import type {
   PlanFullState,
   ProjectConfig,
   ProjectState,
+  ReviewResult,
   Sprint,
+  SprintArtifacts,
+  SprintExecutionSummary,
   SprintIssueSummary,
   Team,
   WorkflowStatus,
+  Workspace,
 } from './types.js';
 
 // ============================================================================
@@ -298,6 +306,7 @@ function parseIssue(content: string, filePath: string): Issue {
     technicalNotes: sections.get('Technical Notes') || null,
     filesToModify: parseListItems(sections.get('Files to Modify') || ''),
     activity: parseListItems(sections.get('Activity') || ''),
+    reviewGate: (['none', 'auto', 'required'].includes(String(fm.review_gate)) ? String(fm.review_gate) : 'auto') as Issue['reviewGate'],
     outputFile: optionalString(fm.output_file),
     body,
     path: filePath,
@@ -341,6 +350,19 @@ function parseSprint(content: string, filePath: string): Sprint {
     });
   }
 
+  // Parse execution_summary if present (JSON object in front matter)
+  let executionSummary: SprintExecutionSummary | null = null;
+  if (fm.execution_summary && typeof fm.execution_summary === 'object') {
+    const es = fm.execution_summary as Record<string, unknown>;
+    executionSummary = {
+      totalIssues: Number(es.total_issues ?? 0),
+      completedIssues: Number(es.completed_issues ?? 0),
+      failedIssues: Number(es.failed_issues ?? 0),
+      totalDuration: Number(es.total_duration ?? 0),
+      waves: Number(es.waves ?? 0),
+    };
+  }
+
   return {
     id: String(fm.id || ''),
     title: String(fm.title || ''),
@@ -353,6 +375,8 @@ function parseSprint(content: string, filePath: string): Sprint {
     completed: optionalNumber(fm.completed),
     issues,
     path: filePath,
+    completedAt: optionalString(fm.completed_at),
+    executionSummary,
   };
 }
 
@@ -388,19 +412,196 @@ function parseMilestone(content: string, filePath: string): Milestone {
   };
 }
 
+// ============================================================================
+// Board Parser
+// ============================================================================
+
+function parseBoard(content: string, filePath: string): Board {
+  const { frontMatter: fm, body } = parseFrontMatter(content);
+  const sections = extractSections(body);
+
+  let executionSummary: BoardExecutionSummary | null = null;
+  if (fm.execution_summary && typeof fm.execution_summary === 'object') {
+    const es = fm.execution_summary as Record<string, unknown>;
+    executionSummary = {
+      totalIssues: Number(es.total_issues ?? 0),
+      completedIssues: Number(es.completed_issues ?? 0),
+      failedIssues: Number(es.failed_issues ?? 0),
+      totalDuration: Number(es.total_duration ?? 0),
+      waves: Number(es.waves ?? 0),
+    };
+  }
+
+  return {
+    id: String(fm.id || ''),
+    title: String(fm.title || ''),
+    status: (fm.status as Board['status']) || 'draft',
+    created: String(fm.created || ''),
+    completedAt: optionalString(fm.completed_at),
+    goal: String(fm.goal || sections.get('Goal') || ''),
+    executionSummary,
+    path: filePath,
+  };
+}
+
+function parseWorkspace(content: string): Workspace {
+  try {
+    const parsed = JSON.parse(content) as Record<string, unknown>;
+    return {
+      activeBoardId: typeof parsed.activeBoardId === 'string' ? parsed.activeBoardId : null,
+      boardOrder: Array.isArray(parsed.boardOrder) ? parsed.boardOrder.map(String) : [],
+    };
+  } catch {
+    return { activeBoardId: null, boardOrder: [] };
+  }
+}
+
+/** Check whether a .pm/ directory uses the board-centric format (has boards/ subdirectory). */
+export function isBoardCentricFormat(pmDir: string): boolean {
+  return existsSync(join(pmDir, 'boards'));
+}
+
+/** Check whether a .pm/ directory uses the legacy flat format (has backlog/ at root, no boards/). */
+function isLegacyFormat(pmDir: string): boolean {
+  return existsSync(join(pmDir, 'backlog')) && !existsSync(join(pmDir, 'boards'));
+}
+
+// ============================================================================
+// Legacy → Board Migration
+// ============================================================================
+
+/** Move all files from a legacy directory into a board subdirectory and remove the source. */
+function moveLegacyDir(srcDir: string, destDir: string): void {
+  if (!existsSync(srcDir)) return;
+  for (const file of readdirSync(srcDir)) {
+    renameSync(join(srcDir, file), join(destDir, file));
+  }
+  rmSync(srcDir, { recursive: true });
+}
+
+/** Move a single file if it exists. */
+function moveLegacyFile(src: string, dest: string): void {
+  if (existsSync(src)) renameSync(src, dest);
+}
+
+/** Copy review files from sprint sandbox directories into the board reviews dir. */
+function copySprintReviews(sprintsDir: string, boardReviewsDir: string): void {
+  for (const entry of readdirSync(sprintsDir)) {
+    if (entry.endsWith('.md')) continue;
+    const reviewsDir = join(sprintsDir, entry, 'reviews');
+    if (!existsSync(reviewsDir)) continue;
+    for (const reviewFile of readdirSync(reviewsDir)) {
+      cpSync(join(reviewsDir, reviewFile), join(boardReviewsDir, reviewFile));
+    }
+  }
+}
+
+/** Find and return the goal from the active sprint .md file. */
+function extractActiveSprintGoal(sprintsDir: string): string {
+  for (const entry of readdirSync(sprintsDir).filter(e => e.endsWith('.md'))) {
+    const content = readFileIfExists(join(sprintsDir, entry));
+    if (!content) continue;
+    const fm = parseFrontMatter(content).frontMatter;
+    if (fm.status === 'active') return String(fm.goal || '');
+  }
+  return '';
+}
+
+/** Migrate sprint reviews and extract the active sprint's goal. */
+function migrateLegacySprints(sprintsDir: string, boardReviewsDir: string): string {
+  if (!existsSync(sprintsDir)) return '';
+  copySprintReviews(sprintsDir, boardReviewsDir);
+  const goal = extractActiveSprintGoal(sprintsDir);
+  rmSync(sprintsDir, { recursive: true });
+  return goal;
+}
+
+/** Clean up migrated issues: remove sprint fields, detect active issues. */
+function cleanupMigratedIssues(boardBacklogDir: string): boolean {
+  if (!existsSync(boardBacklogDir)) return false;
+  let hasActive = false;
+
+  for (const file of readdirSync(boardBacklogDir).filter(f => f.endsWith('.md'))) {
+    const content = readFileIfExists(join(boardBacklogDir, file));
+    if (!content) continue;
+    if (content.match(/^status:\s*(in_progress|in_review|todo)/m)) hasActive = true;
+    if (content.match(/^sprint:\s*.+$/m)) {
+      writeFileSync(join(boardBacklogDir, file), content.replace(/^sprint:\s*.+\n?/m, ''), 'utf-8');
+    }
+  }
+  return hasActive;
+}
+
+/** Write the board metadata files (board.md, workspace.json, STATE.md, progress.md). */
+function writeBoardMetadata(pmDir: string, boardDir: string, boardId: string, sprintGoal: string, hasActive: boolean): void {
+  const today = new Date().toISOString().slice(0, 10);
+  const boardMd = [
+    '---', `id: ${boardId}`, 'title: "Board 1"',
+    `status: ${hasActive ? 'active' : 'draft'}`, `created: "${today}"`,
+    'completed_at: null', `goal: "${sprintGoal.replace(/"/g, '\\"')}"`,
+    '---', '', '# Board 1', '',
+    sprintGoal ? `## Goal\n${sprintGoal}\n` : '',
+  ].join('\n');
+  writeFileSync(join(boardDir, 'board.md'), boardMd, 'utf-8');
+
+  const workspace: Workspace = { activeBoardId: boardId, boardOrder: [boardId] };
+  writeFileSync(join(pmDir, 'workspace.json'), JSON.stringify(workspace, null, 2), 'utf-8');
+
+  if (!existsSync(join(boardDir, 'STATE.md'))) {
+    writeFileSync(join(boardDir, 'STATE.md'), [
+      '---', 'project: ../../project.md', 'board: board.md', 'paused: false', '---', '',
+      '# Board State', '', '## Ready to Work', '', '## In Progress', '',
+      '## Blocked', '', '## Recently Completed', '', '## Warnings', '',
+    ].join('\n'), 'utf-8');
+  }
+  if (!existsSync(join(boardDir, 'progress.md'))) {
+    writeFileSync(join(boardDir, 'progress.md'), '# Board Progress\n', 'utf-8');
+  }
+}
+
+/**
+ * Migrate a legacy flat .pm/ directory to board-centric format.
+ * Creates BOARD-001 from the existing backlog, state, outputs, and reviews.
+ */
+function migrateToBoards(pmDir: string): void {
+  const boardId = 'BOARD-001';
+  const boardDir = join(pmDir, 'boards', boardId);
+
+  mkdirSync(boardDir, { recursive: true });
+  mkdirSync(join(boardDir, 'backlog'), { recursive: true });
+  mkdirSync(join(boardDir, 'out'), { recursive: true });
+  mkdirSync(join(boardDir, 'reviews'), { recursive: true });
+
+  moveLegacyDir(join(pmDir, 'backlog'), join(boardDir, 'backlog'));
+  moveLegacyFile(join(pmDir, 'STATE.md'), join(boardDir, 'STATE.md'));
+  moveLegacyDir(join(pmDir, 'out'), join(boardDir, 'out'));
+  moveLegacyFile(join(pmDir, 'progress.md'), join(boardDir, 'progress.md'));
+
+  const sprintGoal = migrateLegacySprints(join(pmDir, 'sprints'), join(boardDir, 'reviews'));
+  const hasActive = cleanupMigratedIssues(join(boardDir, 'backlog'));
+  writeBoardMetadata(pmDir, boardDir, boardId, sprintGoal, hasActive);
+}
+
 // ============================================================================
 // Directory Parser
 // ============================================================================
 
-/** Resolve the PM directory — prefers .pm/, falls back to legacy .plan/ */
+/** Resolve the PM directory — prefers .mstro/pm/, falls back to legacy .pm/ and .plan/ */
 export function resolvePmDir(workingDir: string): string | null {
-  const pmDir = join(workingDir, '.pm');
-  if (existsSync(pmDir)) return pmDir;
-  const legacyDir = join(workingDir, '.plan');
-  if (existsSync(legacyDir)) return legacyDir;
+  const mstroPmDir = join(workingDir, '.mstro', 'pm');
+  if (existsSync(mstroPmDir)) return mstroPmDir;
+  const legacyPmDir = join(workingDir, '.pm');
+  if (existsSync(legacyPmDir)) return legacyPmDir;
+  const legacyPlanDir = join(workingDir, '.plan');
+  if (existsSync(legacyPlanDir)) return legacyPlanDir;
   return null;
 }
 
+/** Default PM directory path for new projects */
+export function defaultPmDir(workingDir: string): string {
+  return join(workingDir, '.mstro', 'pm');
+}
+
 export function planDirExists(workingDir: string): boolean {
   return resolvePmDir(workingDir) !== null;
 }
@@ -424,35 +625,89 @@ function readMdFilesInDir(dirPath: string): Array<{ name: string; content: strin
   } catch { return []; }
 }
 
-export function parsePlanDirectory(workingDir: string): PlanFullState | null {
-  const planDir = resolvePmDir(workingDir);
-  if (!planDir) return null;
+const defaultProject: ProjectConfig = {
+  name: '', id: '', created: '', status: 'active', estimation: 'none',
+  idPrefixes: {}, workflows: [], labels: [], teams: [],
+};
+
+const defaultState: ProjectState = {
+  project: '', currentSprint: null, activeMilestone: null, paused: false,
+  lastSession: null, readyToWork: [], inProgress: [], blocked: [],
+  recentlyCompleted: [], warnings: [],
+};
+
+/** Parse a single board's full state (board.md + STATE.md + backlog/). */
+export function parseBoardDirectory(pmDir: string, boardId: string): BoardFullState | null {
+  const boardDir = join(pmDir, 'boards', boardId);
+  if (!existsSync(boardDir)) return null;
+
+  const boardContent = readFileIfExists(join(boardDir, 'board.md'));
+  if (!boardContent) return null;
+  const board = parseBoard(boardContent, `boards/${boardId}/board.md`);
+
+  const stateContent = readFileIfExists(join(boardDir, 'STATE.md'));
+  const state = stateContent ? parseProjectState(stateContent) : { ...defaultState };
+
+  const issueFiles = readMdFilesInDir(join(boardDir, 'backlog'));
+  const boardPrefix = `boards/${boardId}/`;
+  const issues = issueFiles.map(f => {
+    const issue = parseIssue(f.content, `${boardPrefix}backlog/${f.name}`);
+    // Normalize blocked_by/blocks to full board-relative paths so dependency resolver matches
+    issue.blockedBy = issue.blockedBy.map(bp => bp.startsWith('boards/') ? bp : `${boardPrefix}${bp}`);
+    issue.blocks = issue.blocks.map(bp => bp.startsWith('boards/') ? bp : `${boardPrefix}${bp}`);
+    if (issue.epic && !issue.epic.startsWith('boards/')) issue.epic = `${boardPrefix}${issue.epic}`;
+    return issue;
+  });
+
+  return { board, state, issues };
+}
 
-  // Parse project.md
-  const projectContent = readFileIfExists(join(planDir, 'project.md'));
-  const project = projectContent
-    ? parseProjectConfig(projectContent)
-    : { name: '', id: '', created: '', status: 'active' as const, estimation: 'none' as const, idPrefixes: {}, workflows: [], labels: [], teams: [] };
+/** Parse all boards from the boards/ directory and resolve the active board. */
+function parseBoardCentricState(planDir: string): { boards: Board[]; workspace: Workspace; activeBoard: BoardFullState | null } {
+  const workspaceContent = readFileIfExists(join(planDir, 'workspace.json'));
+  const workspace = workspaceContent ? parseWorkspace(workspaceContent) : { activeBoardId: null, boardOrder: [] };
+
+  const boards: Board[] = [];
+  const boardsDir = join(planDir, 'boards');
+  if (existsSync(boardsDir)) {
+    for (const entry of readdirSync(boardsDir)) {
+      const boardMdPath = join(boardsDir, entry, 'board.md');
+      if (!existsSync(boardMdPath)) continue;
+      boards.push(parseBoard(readFileSync(boardMdPath, 'utf-8'), `boards/${entry}/board.md`));
+    }
+  }
+
+  const orderMap = new Map(workspace.boardOrder.map((id, i) => [id, i]));
+  boards.sort((a, b) => (orderMap.get(a.id) ?? 999) - (orderMap.get(b.id) ?? 999));
 
-  // Parse STATE.md
-  const stateContent = readFileIfExists(join(planDir, 'STATE.md'));
-  const state = stateContent
-    ? parseProjectState(stateContent)
-    : { project: '', currentSprint: null, activeMilestone: null, paused: false, lastSession: null, readyToWork: [], inProgress: [], blocked: [], recentlyCompleted: [], warnings: [] };
+  const activeBoard = workspace.activeBoardId ? parseBoardDirectory(planDir, workspace.activeBoardId) : null;
+  return { boards, workspace, activeBoard };
+}
 
-  // Parse backlog issues
-  const issueFiles = readMdFilesInDir(join(planDir, 'backlog'));
-  const issues = issueFiles.map(f => parseIssue(f.content, `backlog/${f.name}`));
+export function parsePlanDirectory(workingDir: string): PlanFullState | null {
+  const planDir = resolvePmDir(workingDir);
+  if (!planDir) return null;
 
-  // Parse sprints
-  const sprintFiles = readMdFilesInDir(join(planDir, 'sprints'));
-  const sprints = sprintFiles.map(f => parseSprint(f.content, `sprints/${f.name}`));
+  if (isLegacyFormat(planDir)) migrateToBoards(planDir);
 
-  // Parse milestones
+  const projectContent = readFileIfExists(join(planDir, 'project.md'));
+  const project = projectContent ? parseProjectConfig(projectContent) : { ...defaultProject };
   const milestoneFiles = readMdFilesInDir(join(planDir, 'milestones'));
   const milestones = milestoneFiles.map(f => parseMilestone(f.content, `milestones/${f.name}`));
 
-  return { project, state, issues, sprints, milestones };
+  if (!isBoardCentricFormat(planDir)) {
+    return {
+      project, state: { ...defaultState }, boards: [], workspace: { activeBoardId: null, boardOrder: [] },
+      activeBoard: null, issues: [], sprints: [], milestones,
+    };
+  }
+
+  const { boards, workspace, activeBoard } = parseBoardCentricState(planDir);
+  return {
+    project, state: activeBoard?.state ?? { ...defaultState },
+    boards, workspace, activeBoard, issues: activeBoard?.issues ?? [],
+    sprints: [], milestones,
+  };
 }
 
 export function parseSingleIssue(workingDir: string, issuePath: string): Issue | null {
@@ -496,3 +751,110 @@ export function getNextId(issues: Issue[], prefix: string): string {
   }
   return `${prefix}-${String(max + 1).padStart(3, '0')}`;
 }
+
+/** Compute the next available board ID (e.g., "BOARD-003") */
+export function getNextBoardId(boards: Board[]): string {
+  let max = 0;
+  for (const board of boards) {
+    const match = board.id.match(/^BOARD-(\d+)$/);
+    if (match) {
+      const num = Number.parseInt(match[1], 10);
+      if (num > max) max = num;
+    }
+  }
+  return `BOARD-${String(max + 1).padStart(3, '0')}`;
+}
+
+/** Compute the next available board number for display title (e.g., "Board 3") */
+export function getNextBoardNumber(boards: Board[]): number {
+  let max = 0;
+  for (const board of boards) {
+    const match = board.title.match(/^Board (\d+)$/);
+    if (match) {
+      const num = Number.parseInt(match[1], 10);
+      if (num > max) max = num;
+    }
+  }
+  return max + 1;
+}
+
+/** Parse board artifacts from boards/BOARD-N/ directory. */
+export function parseBoardArtifacts(workingDir: string, boardId: string): BoardArtifacts | null {
+  const pmDir = resolvePmDir(workingDir);
+  if (!pmDir) return null;
+
+  const boardDir = join(pmDir, 'boards', boardId);
+  if (!existsSync(boardDir)) return null;
+
+  const progressLog = readFileIfExists(join(boardDir, 'progress.md')) ?? '';
+
+  const outDir = join(boardDir, 'out');
+  let outputFiles: string[] = [];
+  if (existsSync(outDir)) {
+    try {
+      outputFiles = readdirSync(outDir).filter(f => f.endsWith('.md'));
+    } catch { /* skip */ }
+  }
+
+  const reviewsDir = join(boardDir, 'reviews');
+  const reviewResults: ReviewResult[] = [];
+  if (existsSync(reviewsDir)) {
+    try {
+      for (const f of readdirSync(reviewsDir).filter(f => f.endsWith('.json'))) {
+        const content = readFileIfExists(join(reviewsDir, f));
+        if (content) {
+          reviewResults.push(JSON.parse(content) as ReviewResult);
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  return { boardId, progressLog, outputFiles, reviewResults };
+}
+
+/** @deprecated Use getNextBoardId — kept for migration compatibility */
+export function getNextSprintId(sprints: Sprint[]): string {
+  let max = 0;
+  for (const sprint of sprints) {
+    const match = sprint.id.match(/^SPRINT-(\d+)$/);
+    if (match) {
+      const num = Number.parseInt(match[1], 10);
+      if (num > max) max = num;
+    }
+  }
+  return `SPRINT-${String(max + 1).padStart(3, '0')}`;
+}
+
+/** @deprecated Use parseBoardArtifacts — kept for migration compatibility */
+export function parseSprintArtifacts(workingDir: string, sprintId: string): SprintArtifacts | null {
+  const pmDir = resolvePmDir(workingDir);
+  if (!pmDir) return null;
+
+  const sandboxDir = join(pmDir, 'sprints', sprintId);
+  if (!existsSync(sandboxDir)) return null;
+
+  const progressLog = readFileIfExists(join(sandboxDir, 'progress.md')) ?? '';
+
+  const outDir = join(sandboxDir, 'out');
+  let outputFiles: string[] = [];
+  if (existsSync(outDir)) {
+    try {
+      outputFiles = readdirSync(outDir).filter(f => f.endsWith('.md'));
+    } catch { /* skip */ }
+  }
+
+  const reviewsDir = join(sandboxDir, 'reviews');
+  const reviewResults: ReviewResult[] = [];
+  if (existsSync(reviewsDir)) {
+    try {
+      for (const f of readdirSync(reviewsDir).filter(f => f.endsWith('.json'))) {
+        const content = readFileIfExists(join(reviewsDir, f));
+        if (content) {
+          reviewResults.push(JSON.parse(content) as ReviewResult);
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  return { sprintId, progressLog, outputFiles, reviewResults };
+}