mstro-app 0.4.2 → 0.4.4

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-core.ts

@@ -0,0 +1,406 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * YAML front-matter parsing and entity parsers for PPS (.pm/) files.
+ */
+
+import type {
+  AcceptanceCriterion,
+  Board,
+  BoardExecutionSummary,
+  Issue,
+  IssueSummary,
+  Milestone,
+  MilestoneEpicSummary,
+  ProjectConfig,
+  ProjectState,
+  Sprint,
+  SprintExecutionSummary,
+  SprintIssueSummary,
+  Team,
+  WorkflowStatus,
+  Workspace,
+} from './types.js';
+
+// ============================================================================
+// Front Matter Extraction
+// ============================================================================
+
+export 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;
+}
+
+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];
+}
+
+export 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
+// ============================================================================
+
+export 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;
+}
+
+export 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;
+}
+
+export 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')) {
+    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;
+    }
+    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 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 optionalNumber(val: unknown): number | null {
+  return val != null ? Number(val) : null;
+}
+
+export 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')),
+  };
+}
+
+export 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') || ''),
+  };
+}
+
+export 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;
+}
+
+export function parseSprint(content: string, filePath: string): Sprint {
+  const { frontMatter: fm, body } = parseFrontMatter(content);
+  const sections = extractSections(body);
+
+  let issues = parseSprintIssues(sections.get('Issues'));
+  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: '' };
+    });
+  }
+
+  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,
+  };
+}
+
+export 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,
+  };
+}
+
+export 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,
+  };
+}
+
+export 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: [] };
+  }
+}

package/server/services/plan/parser-migration.ts

@@ -0,0 +1,128 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Legacy → Board-centric migration for .pm/ directories.
+ */
+
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseFrontMatter } from './parser-core.js';
+
+/** Check whether a .pm/ directory uses the legacy flat format (has backlog/ at root, no boards/). */
+export function isLegacyFormat(pmDir: string): boolean {
+  return existsSync(join(pmDir, 'backlog')) && !existsSync(join(pmDir, 'boards'));
+}
+
+function readFileIfExists(path: string): string | null {
+  try {
+    if (existsSync(path)) return readFileSync(path, 'utf-8');
+  } catch { /* skip */ }
+  return null;
+}
+
+/** 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 active sprint data into the board and archive sprints dir. */
+function migrateLegacySprints(sprintsDir: string, boardReviewsDir: string): string {
+  if (!existsSync(sprintsDir)) return '';
+  const goal = extractActiveSprintGoal(sprintsDir);
+  copySprintReviews(sprintsDir, boardReviewsDir);
+  return goal;
+}
+
+/** Remove issues from the board backlog that are already tracked via paths in STATE.md */
+function cleanupMigratedIssues(boardBacklogDir: string): boolean {
+  let hasActive = false;
+  for (const f of readdirSync(boardBacklogDir).filter(f => f.endsWith('.md'))) {
+    const content = readFileIfExists(join(boardBacklogDir, f));
+    if (!content) continue;
+    const fm = parseFrontMatter(content).frontMatter;
+    const status = String(fm.status || 'backlog');
+    if (status === 'done' || status === 'closed' || status === 'cancelled') {
+      rmSync(join(boardBacklogDir, f));
+    } else if (status !== 'backlog') {
+      hasActive = true;
+    }
+  }
+  return hasActive;
+}
+
+/** Write the board.md metadata file and optionally a STATE.md for active boards. */
+function writeBoardMetadata(pmDir: string, boardDir: string, boardId: string, sprintGoal: string, hasActive: boolean): void {
+  const today = new Date().toISOString().split('T')[0];
+  const goal = sprintGoal || 'Migrated board';
+  writeFileSync(join(boardDir, 'board.md'), [
+    '---', `id: ${boardId}`, `title: Board 1`, `status: ${hasActive ? 'active' : 'draft'}`,
+    `created: ${today}`, `goal: ${goal}`, '---', '', `# Board 1`, '', `## Goal`, '', goal, '',
+  ].join('\n'));
+
+  // Copy existing STATE.md into the board directory
+  const legacyState = readFileIfExists(join(pmDir, 'STATE.md'));
+  if (legacyState) {
+    writeFileSync(join(boardDir, 'STATE.md'), legacyState);
+  }
+
+  // Write workspace.json pointing at the new board
+  writeFileSync(join(pmDir, 'workspace.json'), JSON.stringify({
+    activeBoardId: boardId, boardOrder: [boardId],
+  }, null, 2));
+}
+
+/** Migrate a legacy flat .pm/ directory to the board-centric format. */
+export function migrateToBoards(pmDir: string): void {
+  const boardId = 'BOARD-001';
+  const boardDir = join(pmDir, 'boards', boardId);
+  mkdirSync(join(boardDir, 'backlog'), { recursive: true });
+  mkdirSync(join(boardDir, 'reviews'), { recursive: true });
+  mkdirSync(join(boardDir, 'out'), { recursive: true });
+
+  moveLegacyDir(join(pmDir, 'backlog'), join(boardDir, 'backlog'));
+  moveLegacyFile(join(pmDir, 'progress.md'), join(boardDir, 'progress.md'));
+
+  const boardReviewsDir = join(boardDir, 'reviews');
+  const sprintGoal = migrateLegacySprints(join(pmDir, 'sprints'), boardReviewsDir);
+  const hasActive = cleanupMigratedIssues(join(boardDir, 'backlog'));
+  writeBoardMetadata(pmDir, boardDir, boardId, sprintGoal, hasActive);
+
+  // Remove migrated top-level items (STATE.md is now inside the board)
+  for (const f of ['STATE.md']) {
+    const p = join(pmDir, f);
+    if (existsSync(p)) rmSync(p);
+  }
+}