mstro-app 0.4.3 → 0.4.4

package/server/services/plan/parser.ts

@@ -2,591 +2,38 @@
 // Licensed under the MIT License. See LICENSE file for details.
 
 /**
- * PPS Parser — Parses .pm/ (or legacy .plan/) directory files into structured TypeScript objects.
+ * PPS Parser — Public API for reading .pm/ (or legacy .plan/) directories.
  *
- * Handles YAML front matter extraction and markdown body parsing.
+ * Entity parsing lives in parser-core.ts; migration in parser-migration.ts.
  */
 
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { parseBoard, parseIssue, parseMilestone, parseProjectConfig, parseProjectState, parseSprint, parseWorkspace } from './parser-core.js';
+import { isLegacyFormat, migrateToBoards } from './parser-migration.js';
 import type {
-  AcceptanceCriterion,
   Board,
   BoardArtifacts,
-  BoardExecutionSummary,
   BoardFullState,
   Issue,
-  IssueSummary,
   Milestone,
-  MilestoneEpicSummary,
   PlanFullState,
   ProjectConfig,
   ProjectState,
   ReviewResult,
   Sprint,
   SprintArtifacts,
-  SprintExecutionSummary,
-  SprintIssueSummary,
-  Team,
-  WorkflowStatus,
   Workspace,
 } from './types.js';
 
 // ============================================================================
-// Front Matter Extraction
+// Directory Resolution
 // ============================================================================
 
-interface ParsedFile {
-  frontMatter: Record<string, unknown>;
-  body: string;
-}
-
-function stripQuotes(v: string): string {
-  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
-    return v.slice(1, -1);
-  }
-  return v;
-}
-
-function parseYamlValue(v: string): unknown {
-  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
-    return v.slice(1, -1);
-  }
-  if (v.startsWith('[') && v.endsWith(']')) {
-    return v.slice(1, -1).split(',').map(s => stripQuotes(s.trim())).filter(Boolean);
-  }
-  if (v === 'true') return true;
-  if (v === 'false') return false;
-  if (v === 'null' || v === '~' || v === '') return null;
-  if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v);
-  return v;
-}
-
-/** Consume indented YAML list items starting after the current index. Returns [items, newIndex]. */
-function consumeIndentedList(lines: string[], startIdx: number): [string[], number] {
-  const items: string[] = [];
-  let i = startIdx;
-  while (i + 1 < lines.length && /^\s+-\s/.test(lines[i + 1])) {
-    i++;
-    const item = lines[i].trim().replace(/^-\s+/, '');
-    items.push(stripQuotes(item));
-  }
-  return [items, i];
-}
-
-function parseFrontMatter(content: string): ParsedFile {
-  const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
-  if (!match) {
-    return { frontMatter: {}, body: content };
-  }
-  const frontMatter: Record<string, unknown> = {};
-  const lines = match[1].split('\n');
-
-  for (let i = 0; i < lines.length; i++) {
-    const trimmed = lines[i].trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-    const colonIdx = trimmed.indexOf(':');
-    if (colonIdx === -1) continue;
-
-    const key = trimmed.slice(0, colonIdx).trim();
-    const rawValue = trimmed.slice(colonIdx + 1).trim();
-
-    if (!rawValue) {
-      const [items, newIdx] = consumeIndentedList(lines, i);
-      i = newIdx;
-      frontMatter[key] = items.length > 0 ? items : null;
-    } else {
-      frontMatter[key] = parseYamlValue(rawValue);
-    }
-  }
-
-  return { frontMatter, body: match[2] };
-}
-
-// ============================================================================
-// Section Extraction
-// ============================================================================
-
-function extractSections(body: string): Map<string, string> {
-  const sections = new Map<string, string>();
-  const lines = body.split('\n');
-  let currentSection = '';
-  let currentContent: string[] = [];
-
-  for (const line of lines) {
-    if (line.startsWith('## ')) {
-      if (currentSection) {
-        sections.set(currentSection, currentContent.join('\n').trim());
-      }
-      currentSection = line.slice(3).trim();
-      currentContent = [];
-    } else {
-      currentContent.push(line);
-    }
-  }
-  if (currentSection) {
-    sections.set(currentSection, currentContent.join('\n').trim());
-  }
-
-  return sections;
-}
-
-function parseCheckboxes(content: string): AcceptanceCriterion[] {
-  const items: AcceptanceCriterion[] = [];
-  for (const line of content.split('\n')) {
-    const match = line.match(/^[-*]\s+\[([ xX])\]\s+(.+)$/);
-    if (match) {
-      items.push({ text: match[2].trim(), checked: match[1] !== ' ' });
-    }
-  }
-  return items;
-}
-
-function parseListItems(content: string): string[] {
-  const items: string[] = [];
-  for (const line of content.split('\n')) {
-    const match = line.match(/^[-*]\s+(.+)$/);
-    if (match) items.push(match[1].trim());
-  }
-  return items;
-}
-
-function parseIssueSummaries(content: string): IssueSummary[] {
-  const summaries: IssueSummary[] = [];
-  for (const line of content.split('\n')) {
-    // Match: 1. [IS-003](backlog/IS-003.md) — Title (P1)
-    const match = line.match(/\d+\.\s+\[([^\]]+)\]\(([^)]+)\)\s*[—–-]\s*(.+?)(?:\s*\((\w+)\))?\s*$/);
-    if (match) {
-      summaries.push({
-        id: match[1],
-        path: match[2],
-        title: match[3].trim(),
-        priority: match[4] || '',
-      });
-      continue;
-    }
-    // Match: - [IS-001](backlog/IS-001.md) — Title
-    const match2 = line.match(/^[-*]\s+\[([^\]]+)\]\(([^)]+)\)\s*[—–-]\s*(.+?)(?:\s*[→→]\s*blocked by\s+\[([^\]]+)\])?\s*$/i);
-    if (match2) {
-      summaries.push({
-        id: match2[1],
-        path: match2[2],
-        title: match2[3].trim(),
-        priority: '',
-        blockedBy: match2[4] || undefined,
-      });
-    }
-  }
-  return summaries;
-}
-
-function parseCompletedSummaries(content: string): IssueSummary[] {
-  const summaries: IssueSummary[] = [];
-  for (const line of content.split('\n')) {
-    const match = line.match(/^[-*]\s+\[([^\]]+)\]\(([^)]+)\)\s*[—–-]\s*(.+?)(?:\s*✓)?\s*$/);
-    if (match) {
-      summaries.push({
-        id: match[1],
-        path: match[2],
-        title: match[3].trim(),
-        priority: '',
-      });
-    }
-  }
-  return summaries;
-}
-
-// ============================================================================
-// Entity Parsers
-// ============================================================================
-
-function parseWorkflows(section: string | undefined): WorkflowStatus[] {
-  if (!section) return [];
-  const workflows: WorkflowStatus[] = [];
-  for (const line of section.split('\n')) {
-    const match = line.match(/\|\s*(\w+)\s*\|\s*(\w+)\s*\|\s*(.+?)\s*\|/);
-    if (match && match[1] !== 'Status') {
-      workflows.push({
-        status: match[1],
-        category: match[2] as WorkflowStatus['category'],
-        description: match[3].trim(),
-      });
-    }
-  }
-  return workflows;
-}
-
-function parseTeams(section: string | undefined): Team[] {
-  if (!section) return [];
-  const teams: Team[] = [];
-  for (const line of section.split('\n')) {
-    const match = line.match(/^[-*]\s+(\w+)(?:\s*[—–-]\s*(.+))?$/);
-    if (match) teams.push({ name: match[1], description: match[2]?.trim() });
-  }
-  return teams;
-}
-
-function parseProjectConfig(content: string): ProjectConfig {
-  const { frontMatter, body } = parseFrontMatter(content);
-  const sections = extractSections(body);
-
-  const idPrefixes: Record<string, string> = {};
-  const rawPrefixes = frontMatter.id_prefixes;
-  if (rawPrefixes && typeof rawPrefixes === 'object') {
-    Object.assign(idPrefixes, rawPrefixes);
-  }
-
-  return {
-    name: String(frontMatter.name || ''),
-    id: String(frontMatter.id || ''),
-    created: String(frontMatter.created || ''),
-    status: (frontMatter.status as ProjectConfig['status']) || 'active',
-    estimation: (frontMatter.estimation as ProjectConfig['estimation']) || 'none',
-    idPrefixes,
-    workflows: parseWorkflows(sections.get('Workflows')),
-    labels: (Array.isArray(frontMatter.labels) ? frontMatter.labels : []) as string[],
-    teams: parseTeams(sections.get('Teams')),
-  };
-}
-
-function parseProjectState(content: string): ProjectState {
-  const { frontMatter, body } = parseFrontMatter(content);
-  const sections = extractSections(body);
-
-  return {
-    project: String(frontMatter.project || ''),
-    currentSprint: (frontMatter.current_sprint as string) || null,
-    activeMilestone: (frontMatter.active_milestone as string) || null,
-    paused: frontMatter.paused === true,
-    lastSession: (frontMatter.last_session as string) || null,
-    readyToWork: parseIssueSummaries(sections.get('Ready to Work') || ''),
-    inProgress: parseIssueSummaries(sections.get('In Progress') || ''),
-    blocked: parseIssueSummaries(sections.get('Blocked') || ''),
-    recentlyCompleted: parseCompletedSummaries(sections.get('Recently Completed') || ''),
-    warnings: parseListItems(sections.get('Warnings') || ''),
-  };
-}
-
-function toStringArray(val: unknown): string[] {
-  return Array.isArray(val) ? val.map(String) : [];
-}
-
-function optionalString(val: unknown): string | null {
-  if (val == null) return null;
-  const s = String(val);
-  return s === '' ? null : s;
-}
-
-function parseIssue(content: string, filePath: string): Issue {
-  const { frontMatter: fm, body } = parseFrontMatter(content);
-  const sections = extractSections(body);
-
-  return {
-    id: String(fm.id || ''),
-    title: String(fm.title || ''),
-    type: (fm.type as Issue['type']) || 'issue',
-    status: String(fm.status || 'backlog'),
-    priority: String(fm.priority || 'P2'),
-    estimate: fm.estimate != null ? fm.estimate as number | string : null,
-    labels: toStringArray(fm.labels),
-    epic: optionalString(fm.epic),
-    sprint: optionalString(fm.sprint),
-    milestone: optionalString(fm.milestone),
-    assigned: optionalString(fm.assigned),
-    created: String(fm.created || ''),
-    updated: optionalString(fm.updated),
-    due: optionalString(fm.due),
-    blockedBy: toStringArray(fm.blocked_by),
-    blocks: toStringArray(fm.blocks),
-    relatesTo: toStringArray(fm.relates_to),
-    children: toStringArray(fm.children),
-    progress: optionalString(fm.progress),
-    description: sections.get('Description') || '',
-    acceptanceCriteria: parseCheckboxes(sections.get('Acceptance Criteria') || ''),
-    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,
-  };
-}
-
-function parseSprintIssues(section: string | undefined): SprintIssueSummary[] {
-  if (!section) return [];
-  const issues: SprintIssueSummary[] = [];
-  for (const line of section.split('\n')) {
-    const match = line.match(/\|\s*\[([^\]]+)\]\(([^)]+)\)\s*\|\s*(.+?)\s*\|\s*(\S+)\s*\|\s*(\S+)\s*\|/);
-    if (match) {
-      issues.push({
-        id: match[1],
-        path: match[2],
-        title: match[3].trim(),
-        points: /^\d+$/.test(match[4]) ? Number(match[4]) : match[4],
-        status: match[5],
-      });
-    }
-  }
-  return issues;
-}
-
-function optionalNumber(val: unknown): number | null {
-  return val != null ? Number(val) : null;
-}
-
-function parseSprint(content: string, filePath: string): Sprint {
-  const { frontMatter: fm, body } = parseFrontMatter(content);
-  const sections = extractSections(body);
-
-  // Table-based parsing (markdown links in table rows)
-  let issues = parseSprintIssues(sections.get('Issues'));
-
-  // Fallback: front matter issues array (e.g., ["backlog/IS-001.md", ...])
-  if (issues.length === 0 && Array.isArray(fm.issues)) {
-    issues = (fm.issues as string[]).map(path => {
-      const id = path.replace(/^backlog\//, '').replace(/\.md$/, '');
-      return { id, path, title: '', points: null, status: '' };
-    });
-  }
-
-  // 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 || ''),
-    status: (fm.status as Sprint['status']) || 'planned',
-    start: String(fm.start || fm.start_date || ''),
-    end: String(fm.end || fm.end_date || ''),
-    goal: String(fm.goal || sections.get('Goal') || sections.get('Sprint Goal') || ''),
-    capacity: optionalNumber(fm.capacity),
-    committed: optionalNumber(fm.committed),
-    completed: optionalNumber(fm.completed),
-    issues,
-    path: filePath,
-    completedAt: optionalString(fm.completed_at),
-    executionSummary,
-  };
-}
-
-function parseMilestone(content: string, filePath: string): Milestone {
-  const { frontMatter, body } = parseFrontMatter(content);
-  const sections = extractSections(body);
-
-  const epics: MilestoneEpicSummary[] = [];
-  const epicSection = sections.get('Epics');
-  if (epicSection) {
-    for (const line of epicSection.split('\n')) {
-      const match = line.match(/\|\s*\[([^\]]+)\]\(([^)]+)\)\s*\|\s*(.+?)\s*\|\s*(\S+)\s*\|/);
-      if (match) {
-        epics.push({
-          id: match[1],
-          path: match[2],
-          title: match[3].trim(),
-          progress: match[4],
-        });
-      }
-    }
-  }
-
-  return {
-    id: String(frontMatter.id || ''),
-    title: String(frontMatter.title || ''),
-    status: (frontMatter.status as Milestone['status']) || 'planned',
-    targetDate: (frontMatter.target_date as string) || null,
-    progress: (frontMatter.progress as string) || null,
-    definition: sections.get('Definition of Done') || '',
-    epics,
-    path: filePath,
-  };
-}
-
-// ============================================================================
-// 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 .mstro/pm/, falls back to legacy .pm/ and .plan/ */
 export function resolvePmDir(workingDir: string): string | null {
   const mstroPmDir = join(workingDir, '.mstro', 'pm');
   if (existsSync(mstroPmDir)) return mstroPmDir;
@@ -597,7 +44,6 @@ export function resolvePmDir(workingDir: string): string | null {
   return null;
 }
 
-/** Default PM directory path for new projects */
 export function defaultPmDir(workingDir: string): string {
   return join(workingDir, '.mstro', 'pm');
 }
@@ -606,6 +52,10 @@ export function planDirExists(workingDir: string): boolean {
   return resolvePmDir(workingDir) !== null;
 }
 
+// ============================================================================
+// File Utilities
+// ============================================================================
+
 function readFileIfExists(path: string): string | null {
   try {
     if (existsSync(path)) return readFileSync(path, 'utf-8');
@@ -618,13 +68,30 @@ function readMdFilesInDir(dirPath: string): Array<{ name: string; content: strin
   try {
     return readdirSync(dirPath)
       .filter(f => f.endsWith('.md'))
-      .map(name => {
-        const content = readFileSync(join(dirPath, name), 'utf-8');
-        return { name, content };
-      });
+      .map(name => ({ name, content: readFileSync(join(dirPath, name), 'utf-8') }));
+  } catch { return []; }
+}
+
+function listDirFiles(dirPath: string, ext: string): string[] {
+  if (!existsSync(dirPath)) return [];
+  try {
+    return readdirSync(dirPath).filter(f => f.endsWith(ext));
   } catch { return []; }
 }
 
+function readReviewResults(reviewsDir: string): ReviewResult[] {
+  const results: ReviewResult[] = [];
+  for (const f of listDirFiles(reviewsDir, '.json')) {
+    const content = readFileIfExists(join(reviewsDir, f));
+    if (content) results.push(JSON.parse(content) as ReviewResult);
+  }
+  return results;
+}
+
+// ============================================================================
+// Defaults
+// ============================================================================
+
 const defaultProject: ProjectConfig = {
   name: '', id: '', created: '', status: 'active', estimation: 'none',
   idPrefixes: {}, workflows: [], labels: [], teams: [],
@@ -636,7 +103,10 @@ const defaultState: ProjectState = {
   recentlyCompleted: [], warnings: [],
 };
 
-/** Parse a single board's full state (board.md + STATE.md + backlog/). */
+// ============================================================================
+// Board & Plan Directory Parsing
+// ============================================================================
+
 export function parseBoardDirectory(pmDir: string, boardId: string): BoardFullState | null {
   const boardDir = join(pmDir, 'boards', boardId);
   if (!existsSync(boardDir)) return null;
@@ -652,7 +122,6 @@ export function parseBoardDirectory(pmDir: string, boardId: string): BoardFullSt
   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}`;
@@ -662,7 +131,6 @@ export function parseBoardDirectory(pmDir: string, boardId: string): BoardFullSt
   return { board, state, issues };
 }
 
-/** 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: [] };
@@ -710,11 +178,14 @@ export function parsePlanDirectory(workingDir: string): PlanFullState | null {
   };
 }
 
+// ============================================================================
+// Single Entity Parsers
+// ============================================================================
+
 export function parseSingleIssue(workingDir: string, issuePath: string): Issue | null {
   const pmDir = resolvePmDir(workingDir);
   if (!pmDir) return null;
-  const fullPath = join(pmDir, issuePath);
-  const content = readFileIfExists(fullPath);
+  const content = readFileIfExists(join(pmDir, issuePath));
   if (!content) return null;
   return parseIssue(content, issuePath);
 }
@@ -722,8 +193,7 @@ export function parseSingleIssue(workingDir: string, issuePath: string): Issue |
 export function parseSingleSprint(workingDir: string, sprintPath: string): Sprint | null {
   const pmDir = resolvePmDir(workingDir);
   if (!pmDir) return null;
-  const fullPath = join(pmDir, sprintPath);
-  const content = readFileIfExists(fullPath);
+  const content = readFileIfExists(join(pmDir, sprintPath));
   if (!content) return null;
   return parseSprint(content, sprintPath);
 }
@@ -731,13 +201,15 @@ export function parseSingleSprint(workingDir: string, sprintPath: string): Sprin
 export function parseSingleMilestone(workingDir: string, milestonePath: string): Milestone | null {
   const pmDir = resolvePmDir(workingDir);
   if (!pmDir) return null;
-  const fullPath = join(pmDir, milestonePath);
-  const content = readFileIfExists(fullPath);
+  const content = readFileIfExists(join(pmDir, milestonePath));
   if (!content) return null;
   return parseMilestone(content, milestonePath);
 }
 
-/** Compute the next available ID for a given prefix (e.g., "IS" → "IS-004") */
+// ============================================================================
+// ID Generation
+// ============================================================================
+
 export function getNextId(issues: Issue[], prefix: string): string {
   const escaped = prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   const pattern = new RegExp(`^${escaped}-(\\d+)$`);
@@ -752,7 +224,6 @@ 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) {
@@ -765,7 +236,6 @@ export function getNextBoardId(boards: Board[]): string {
   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) {
@@ -778,7 +248,6 @@ export function getNextBoardNumber(boards: Board[]): number {
   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;
@@ -787,29 +256,11 @@ export function parseBoardArtifacts(workingDir: string, boardId: string): BoardA
   if (!existsSync(boardDir)) return null;
 
   const progressLog = readFileIfExists(join(boardDir, 'progress.md')) ?? '';
+  const outputFiles = listDirFiles(join(boardDir, 'out'), '.md');
+  const reviewResults = readReviewResults(join(boardDir, 'reviews'));
+  const executionLogs = listDirFiles(join(boardDir, 'logs'), '.log').sort();
 
-  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 };
+  return { boardId, progressLog, outputFiles, reviewResults, executionLogs };
 }
 
 /** @deprecated Use getNextBoardId — kept for migration compatibility */
@@ -834,27 +285,8 @@ export function parseSprintArtifacts(workingDir: string, sprintId: string): Spri
   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 */ }
-  }
+  const outputFiles = listDirFiles(join(sandboxDir, 'out'), '.md');
+  const reviewResults = readReviewResults(join(sandboxDir, 'reviews'));
 
   return { sprintId, progressLog, outputFiles, reviewResults };
 }