mstro-app 0.4.2 → 0.4.4

package/server/services/plan/prompt-builder.ts

@@ -0,0 +1,161 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Prompt Builder — Constructs the Agent Teams coordinator prompt.
+ *
+ * Builds a structured prompt for the team lead that spawns teammates
+ * using Agent Teams, waits for completion, and verifies outputs.
+ */
+
+import { join } from 'node:path';
+import type { Issue } from './types.js';
+
+export interface CoordinatorPromptOptions {
+  issues: Issue[];
+  workingDir: string;
+  pmDir: string | null;
+  /** Board directory path when executing a board (e.g. /path/.pm/boards/BOARD-001). */
+  boardDir: string | null;
+  existingDocs: string[];
+  resolveOutputPath: (issue: Issue) => string;
+}
+
+/**
+ * Build the team lead prompt for a wave of issues.
+ * Uses Agent Teams for true parallel execution — each teammate gets
+ * its own context window and sends idle notifications when done.
+ */
+export function buildCoordinatorPrompt(options: CoordinatorPromptOptions): string {
+  const { issues, workingDir, pmDir, boardDir, existingDocs, resolveOutputPath } = options;
+  const outDir = boardDir ? join(boardDir, 'out') : pmDir ? join(pmDir, 'out') : join(workingDir, '.mstro', 'pm', 'out');
+
+  const issueBlocks = issues.map(issue => {
+    const criteria = issue.acceptanceCriteria
+      .map(c => `- [${c.checked ? 'x' : ' '}] ${c.text}`)
+      .join('\n');
+
+    const files = issue.filesToModify.length > 0
+      ? `\nFiles to modify:\n${issue.filesToModify.map(f => `- ${f}`).join('\n')}`
+      : '';
+
+    const predecessorDocs = resolvePredecessorDocs(issue, existingDocs);
+    const predecessorSection = predecessorDocs.length > 0
+      ? `\nPredecessor outputs to read:\n${predecessorDocs.map(d => `- ${d}`).join('\n')}`
+      : '';
+
+    return `### ${issue.id}: ${issue.title}
+
+**Type**: ${issue.type} | **Priority**: ${issue.priority} | **Estimate**: ${issue.estimate ?? 'unestimated'}
+
+**Description**:
+${issue.description}
+
+**Acceptance Criteria**:
+${criteria || 'No specific criteria defined.'}
+
+**Technical Notes**:
+${issue.technicalNotes || 'None'}
+${files}${predecessorSection}
+
+**Output file**: ${resolveOutputPath(issue)}`;
+  }).join('\n\n---\n\n');
+
+  const teamName = `pm-wave-${Date.now()}`;
+
+  const teammateSpawns = issues.map(issue => {
+    const predecessorDocs = resolvePredecessorDocs(issue, existingDocs);
+    const predInstr = predecessorDocs.length > 0
+      ? `Read these predecessor output docs before starting: ${predecessorDocs.join(', ')}. `
+      : '';
+
+    const outputFile = resolveOutputPath(issue);
+
+    const fileOwnership = issue.filesToModify.length > 0
+      ? `\n> FILE OWNERSHIP: You own these files exclusively: ${issue.filesToModify.join(', ')}. Other teammates own all other files.`
+      : '';
+
+    return `Spawn teammate **${issue.id.toLowerCase()}** using the **Agent** tool with \`team_name: "${teamName}"\` and \`name: "${issue.id.toLowerCase()}"\`:
+> ${predInstr}Work on issue ${issue.id}: ${issue.title}.
+> Read the full spec at ${pmDir ? join(pmDir, issue.path) : issue.path}.
+> Execute all acceptance criteria.
+> Write all output and results to ${outputFile} — this is the handoff artifact for downstream issues.
+> After writing output, update the issue front matter: change \`status: in_progress\` to \`status: done\`.
+> The orchestrator manages STATE.md. Stay within this issue's scope.${fileOwnership}`;
+  }).join('\n\n');
+
+  return `You are the team lead coordinating ${issues.length} issue${issues.length > 1 ? 's' : ''} using Agent Teams.
+
+## Project Directory
+Working directory: ${workingDir}
+Plan directory: ${pmDir || '.mstro/pm/'}
+
+## Issues to Execute
+
+${issueBlocks}
+
+## Execution Protocol — Agent Teams
+
+All team coordination uses exactly two tools:
+- **Agent** — spawn teammates (include \`team_name\` and \`name\` in each call)
+- **SendMessage** — message teammates after they are spawned
+
+### Step 1: Spawn all teammates in one message
+
+Send a single message containing ${issues.length} **Agent** tool calls. Include \`team_name: "${teamName}"\` and a unique \`name\` in each call. The team starts automatically when the first teammate is spawned — the \`team_name\` parameter handles all setup.
+
+${teammateSpawns}
+
+### Step 2: Wait for every teammate to finish
+
+After spawning, idle notifications arrive automatically as messages — you will be notified when each teammate finishes. Between notifications, you have nothing to do. Simply state that you are waiting and let the system deliver notifications to you.
+
+Your first action after spawning all teammates: output a brief status message listing all teammates and confirming you are waiting for their idle notifications. Then wait.
+
+Track completion against this checklist — proceed to Step 3 only after all are checked:
+${issues.map(i => `- [ ] ${i.id.toLowerCase()}`).join('\n')}
+
+Exact teammate names for SendMessage (messages to any other name are silently dropped):
+${issues.map(i => `- \`${i.id.toLowerCase()}\``).join('\n')}
+
+When you receive an idle notification from a teammate:
+- Check off that teammate in the checklist above
+- Verify their output file exists on disk using the **Read** tool
+
+If 15 minutes pass without an idle notification from a specific teammate, send them a progress check via **SendMessage** using the exact name from the list above. After 5 more minutes with no response, check their output file and issue status on disk — if the output exists and status is \`done\`, mark them complete. Otherwise, update the issue status based on whatever partial work exists, then continue.
+
+Staying active until all teammates finish is essential — when the lead exits, all teammate processes stop and their in-progress work is lost. When unsure whether a teammate is still working, keep waiting.
+
+### Step 3: Verify outputs
+
+Once every teammate has completed or been handled:
+1. Verify each output file exists in ${outDir}/ using **Read** or **Glob**
+2. Verify each issue's front matter status is \`done\`
+3. For any missing output or status update, write it yourself
+4. The orchestrator manages STATE.md separately — focus on output files and issue front matter only
+
+### Step 4: Clean up and exit
+
+After all outputs are verified:
+- Send each remaining active teammate a shutdown message via **SendMessage**
+- Then exit — the orchestrator handles the next wave
+
+## Coordination Rules
+
+- The team starts implicitly when you spawn the first teammate with \`team_name\`. Cleanup happens automatically when all teammates exit or the lead exits.
+- Wait for idle notifications from all ${issues.length} teammates before exiting — this ensures all work is saved to disk.
+- Each teammate writes its output to disk (the handoff artifact for downstream issues). Research kept only in conversation is lost when the teammate exits.
+- Each teammate updates its issue front matter status to \`done\` when finished.
+- One issue per teammate — each teammate stays within its assigned scope.
+- Use only the exact teammate names listed above for SendMessage.`;
+}
+
+/** Find predecessor output docs that an issue should read based on its blockedBy dependencies. */
+function resolvePredecessorDocs(issue: Issue, existingDocs: string[]): string[] {
+  return issue.blockedBy
+    .map(bp => {
+      const blockerId = bp.replace(/^backlog\//, '').replace(/\.md$/, '');
+      return existingDocs.find(d => d.toLowerCase().includes(blockerId.toLowerCase()));
+    })
+    .filter(Boolean) as string[];
+}

package/server/services/plan/review-gate.ts

@@ -0,0 +1,212 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Review Gate — AI-powered quality gate for completed issues.
+ *
+ * Code tasks: reads modified files, checks acceptance criteria, looks for bugs.
+ * Non-code tasks: reads output doc, checks criteria and completeness.
+ * Auto-passes on infrastructure failures to avoid blocking execution.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runWithFileLogger } from '../../cli/headless/headless-logger.js';
+import { HeadlessRunner } from '../../cli/headless/index.js';
+import type { Issue, ReviewCheck, ReviewResult } from './types.js';
+
+/** Max review attempts per issue per sprint before giving up */
+export const MAX_REVIEW_ATTEMPTS = 3;
+
+/** Review runner stall timeouts (ms) */
+const REVIEW_STALL_WARNING_MS = 300_000;   // 5 min
+const REVIEW_STALL_KILL_MS = 600_000;      // 10 min
+const REVIEW_STALL_HARD_CAP_MS = 900_000;  // 15 min
+
+export interface ReviewIssueOptions {
+  workingDir: string;
+  issue: Issue;
+  pmDir: string;
+  outputPath: string;
+  onOutput?: (text: string) => void;
+  /** Board-scoped log directory for execution logs. Falls back to global ~/.mstro/logs/headless/ */
+  logDir?: string;
+}
+
+/**
+ * Run an AI review for a completed issue.
+ * Returns auto-pass on infrastructure failures to avoid blocking execution.
+ */
+export async function reviewIssue(options: ReviewIssueOptions): Promise<ReviewResult> {
+  const { workingDir, issue, pmDir, outputPath, onOutput, logDir } = options;
+  const isCodeTask = issue.filesToModify.length > 0;
+  const issueType: ReviewResult['issueType'] = isCodeTask ? 'code' : 'non-code';
+
+  try {
+    const prompt = buildReviewPrompt(issue, pmDir, outputPath, isCodeTask);
+
+    const runner = new HeadlessRunner({
+      workingDir,
+      directPrompt: prompt,
+      stallWarningMs: REVIEW_STALL_WARNING_MS,
+      stallKillMs: REVIEW_STALL_KILL_MS,
+      stallHardCapMs: REVIEW_STALL_HARD_CAP_MS,
+      verbose: false,
+      outputCallback: onOutput ? (text: string) => onOutput(`Review: ${text}`) : undefined,
+    });
+
+    const result = await runWithFileLogger('pm-review', () => runner.run(), logDir);
+
+    if (result.completed && result.assistantResponse) {
+      return parseReviewOutput(issue.id, issueType, result.assistantResponse);
+    }
+
+    return autoPassResult(issue.id, issueType, 'Review runner did not complete');
+  } catch {
+    return autoPassResult(issue.id, issueType, 'Review threw an error');
+  }
+}
+
+/** Count existing review result files for this issue in the board/sprint directory. */
+export function getReviewAttemptCount(boardOrSandboxDir: string | null, issue: Issue): number {
+  if (!boardOrSandboxDir) return 0;
+  const reviewsDir = join(boardOrSandboxDir, 'reviews');
+  if (!existsSync(reviewsDir)) return 0;
+  try {
+    return readdirSync(reviewsDir).filter(f => f.startsWith(issue.id) && f.endsWith('.json')).length;
+  } catch {
+    return 0;
+  }
+}
+
+/** Persist a review result as JSON in the board/sprint reviews directory. */
+export function persistReviewResult(boardOrSandboxDir: string | null, issue: Issue, result: ReviewResult): void {
+  if (!boardOrSandboxDir) return;
+  const reviewsDir = join(boardOrSandboxDir, 'reviews');
+  if (!existsSync(reviewsDir)) mkdirSync(reviewsDir, { recursive: true });
+  try {
+    writeFileSync(
+      join(reviewsDir, `${issue.id}-${Date.now()}.json`),
+      JSON.stringify(result, null, 2),
+      'utf-8',
+    );
+  } catch { /* non-fatal */ }
+}
+
+/** Append failed review checks to an issue's Activity section. */
+export function appendReviewFeedback(pmDir: string, issue: Issue, result: ReviewResult): void {
+  const fullPath = join(pmDir, issue.path);
+  try {
+    let content = readFileSync(fullPath, 'utf-8');
+    const failedChecks = result.checks.filter(c => !c.passed);
+    const feedback = failedChecks.map(c => `  - ${c.name}: ${c.details}`).join('\n');
+    const entry = `- Review failed (${new Date().toISOString().split('T')[0]}): ${failedChecks.length} check(s) failed\n${feedback}`;
+
+    if (content.includes('## Activity')) {
+      content = content.replace(/## Activity/, `## Activity\n${entry}`);
+    } else {
+      content += `\n\n## Activity\n${entry}`;
+    }
+    writeFileSync(fullPath, content, 'utf-8');
+  } catch { /* non-fatal */ }
+}
+
+/** Extract the outermost JSON object from AI output using brace balancing. */
+function extractJsonObject(text: string): string | null {
+  const start = text.indexOf('{');
+  if (start === -1) return null;
+  let depth = 0;
+  for (let i = start; i < text.length; i++) {
+    if (text[i] === '{') depth++;
+    else if (text[i] === '}') depth--;
+    if (depth === 0) return text.slice(start, i + 1);
+  }
+  return null;
+}
+
+/** Parse structured JSON review output from AI response. */
+export function parseReviewOutput(issueId: string, issueType: ReviewResult['issueType'], output: string): ReviewResult {
+  const jsonStr = extractJsonObject(output);
+  if (jsonStr) {
+    try {
+      const parsed = JSON.parse(jsonStr);
+      if (typeof parsed.passed === 'boolean' || typeof parsed.passed === 'number') {
+        return {
+          issueId,
+          issueType,
+          passed: !!parsed.passed,
+          checks: Array.isArray(parsed.checks) ? parsed.checks.map((c: Record<string, unknown>) => ({
+            name: String(c.name ?? 'unknown'),
+            passed: !!c.passed,
+            details: String(c.details ?? ''),
+          } satisfies ReviewCheck)) : [],
+          reviewedAt: new Date().toISOString(),
+        };
+      }
+    } catch { /* fall through */ }
+  }
+  return autoPassResult(issueId, issueType, 'Could not parse review output');
+}
+
+/** Create a passing review result for infrastructure failures. */
+export function autoPassResult(issueId: string, issueType: ReviewResult['issueType'], reason: string): ReviewResult {
+  return {
+    issueId,
+    issueType,
+    passed: true,
+    autoPass: true,
+    checks: [{ name: 'review_infrastructure', passed: true, details: `${reason}; auto-passing` }],
+    reviewedAt: new Date().toISOString(),
+  };
+}
+
+// ── Private helpers ─────────────────────────────────────────
+
+function buildReviewPrompt(issue: Issue, pmDir: string, outputPath: string, isCodeTask: boolean): string {
+  const criteria = issue.acceptanceCriteria
+    .map(c => `- [${c.checked ? 'x' : ' '}] ${c.text}`)
+    .join('\n');
+
+  if (isCodeTask) {
+    return `You are a code reviewer. Review the work done for issue ${issue.id}: ${issue.title}.
+
+## Files Modified
+${issue.filesToModify.map(f => `- ${f}`).join('\n')}
+
+## Acceptance Criteria
+${criteria || 'No specific criteria defined.'}
+
+## Instructions
+1. Read each modified file listed above
+2. Check if all acceptance criteria are met by the code changes
+3. Look for obvious bugs, security vulnerabilities, or code quality issues
+4. Check if the output artifact exists at: ${outputPath}
+
+Output EXACTLY one JSON object on its own line (no markdown fencing):
+{"passed": true, "checks": [{"name": "criteria_met", "passed": true, "details": "..."}]}
+
+Include checks for: criteria_met, code_quality, no_obvious_bugs.`;
+  }
+
+  return `You are a quality reviewer. Review the work done for issue ${issue.id}: ${issue.title}.
+
+## Output File
+${outputPath}
+
+## Issue Spec
+${join(pmDir, issue.path)}
+
+## Acceptance Criteria
+${criteria || 'No specific criteria defined.'}
+
+## Instructions
+1. Read the output file at the path above
+2. Read the full issue spec
+3. Check if all acceptance criteria are met
+4. Check for completeness and quality of the output
+
+Output EXACTLY one JSON object on its own line (no markdown fencing):
+{"passed": true, "checks": [{"name": "criteria_met", "passed": true, "details": "..."}]}
+
+Include checks for: criteria_met, output_quality, completeness.`;
+}

package/server/services/plan/state-reconciler.ts

@@ -11,7 +11,8 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolveReadyToWork } from './dependency-resolver.js';
-import { parsePlanDirectory, resolvePmDir } from './parser.js';
+import { replaceFrontMatterField, replaceYamlField } from './front-matter.js';
+import { isBoardCentricFormat, parseBoardDirectory, parsePlanDirectory, resolvePmDir } from './parser.js';
 import type { Issue, Sprint } from './types.js';
 
 interface CategorizedIssues {
@@ -69,6 +70,7 @@ function buildStateMarkdown(
   categories: CategorizedIssues,
   warnings: string[],
   issueByPath: Map<string, Issue>,
+  header = '# Project State',
 ): string {
   const formatSummary = (issue: Issue, index: number): string => {
     return `${index + 1}. [${issue.id}](${issue.path}) — ${issue.title} (${issue.priority})`;
@@ -83,7 +85,7 @@ function buildStateMarkdown(
   };
 
   const sections = [
-    '# Project State',
+    header,
     '',
     '## Current Focus',
     '',
@@ -138,7 +140,14 @@ function reconcileSprintStatuses(pmDir: string, sprints: Sprint[], issueByPath:
     const sprintPath = join(pmDir, sprint.path);
     try {
       let content = readFileSync(sprintPath, 'utf-8');
-      content = content.replace(/^(status:\s*).+$/m, `$1${derived}`);
+      content = replaceFrontMatterField(content, 'status', derived);
+
+      // Write completed_at when transitioning to completed
+      if (derived === 'completed' && !content.match(/^completed_at:/m)) {
+        const timestamp = new Date().toISOString().split('T')[0];
+        content = replaceFrontMatterField(content, 'completed_at', timestamp);
+      }
+
       writeFileSync(sprintPath, content, 'utf-8');
     } catch {
       // Sprint file may be missing or unwritable
@@ -146,9 +155,17 @@ function reconcileSprintStatuses(pmDir: string, sprints: Sprint[], issueByPath:
   }
 }
 
-export function reconcileState(workingDir: string): void {
+export function reconcileState(workingDir: string, boardId?: string): void {
   const pmDir = resolvePmDir(workingDir);
   if (!pmDir) return;
+
+  // Board-centric: reconcile a specific board's STATE.md
+  if (isBoardCentricFormat(pmDir)) {
+    reconcileBoardState(pmDir, workingDir, boardId);
+    return;
+  }
+
+  // Legacy sprint-based reconciliation
   const statePath = join(pmDir, 'STATE.md');
   if (!existsSync(statePath)) return;
 
@@ -166,9 +183,53 @@ export function reconcileState(workingDir: string): void {
   const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
   const frontMatter = fmMatch ? fmMatch[1] : `project: "${project.name}"\ncurrent_sprint: null\nactive_milestone: null\npaused: false\nlast_session: null`;
 
-  const newContent = buildStateMarkdown(frontMatter, categories, warnings, issueByPath);
-  writeFileSync(statePath, newContent, 'utf-8');
-
   // Reconcile sprint statuses from actual issue statuses
   reconcileSprintStatuses(pmDir, sprints, issueByPath);
+
+  // Update current_sprint in front matter based on actual sprint statuses
+  const recomputedActive = sprints.find(s => {
+    const derived = deriveSprintStatus(s, issueByPath);
+    return (derived ?? s.status) === 'active';
+  });
+  const updatedFM = replaceYamlField(frontMatter, 'current_sprint', recomputedActive ? recomputedActive.id : 'null');
+
+  const newContent = buildStateMarkdown(updatedFM, categories, warnings, issueByPath);
+  writeFileSync(statePath, newContent, 'utf-8');
+}
+
+function reconcileBoardState(pmDir: string, _workingDir: string, boardId?: string): void {
+  // Determine which board to reconcile
+  const effectiveBoardId = boardId ?? resolveActiveBoardId(pmDir);
+  if (!effectiveBoardId) return;
+
+  const boardState = parseBoardDirectory(pmDir, effectiveBoardId);
+  if (!boardState) return;
+
+  const statePath = join(pmDir, 'boards', effectiveBoardId, 'STATE.md');
+  if (!existsSync(statePath)) return;
+
+  const { board, issues } = boardState;
+
+  const issueByPath = new Map(issues.map(i => [i.path, i]));
+  const categories = categorizeIssues(issues, issueByPath);
+  const warnings = computeWarnings(issues);
+
+  // Read existing front matter from the board's STATE.md
+  const content = readFileSync(statePath, 'utf-8');
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  const frontMatter = fmMatch ? fmMatch[1] : `board: "${board.id}"\npaused: false\nlast_session: null`;
+
+  const newContent = buildStateMarkdown(frontMatter, categories, warnings, issueByPath, '# Board State');
+  writeFileSync(statePath, newContent, 'utf-8');
+}
+
+function resolveActiveBoardId(pmDir: string): string | null {
+  const wsPath = join(pmDir, 'workspace.json');
+  if (!existsSync(wsPath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(wsPath, 'utf-8'));
+    return typeof parsed.activeBoardId === 'string' ? parsed.activeBoardId : null;
+  } catch {
+    return null;
+  }
 }

package/server/services/plan/types.ts

@@ -92,6 +92,8 @@ export interface Issue {
   children: string[];
   // Progress (for epics)
   progress: string | null;
+  // Review gate mode (none = skip review, auto = AI review, required = human review)
+  reviewGate: 'none' | 'auto' | 'required';
   // Planned output file path (from front matter output_file, relative to working dir)
   outputFile: string | null;
   // Full markdown body
@@ -106,7 +108,39 @@ export interface AcceptanceCriterion {
 }
 
 // ============================================================================
-// Sprint (sprints/*.md)
+// Board (boards/BOARD-N/board.md)
+// ============================================================================
+
+export interface Board {
+  id: string;
+  title: string;
+  status: 'draft' | 'active' | 'completed' | 'archived';
+  created: string;
+  completedAt: string | null;
+  goal: string;
+  executionSummary: BoardExecutionSummary | null;
+  path: string;
+}
+
+export interface BoardExecutionSummary {
+  totalIssues: number;
+  completedIssues: number;
+  failedIssues: number;
+  totalDuration: number;
+  waves: number;
+}
+
+// ============================================================================
+// Workspace (workspace.json)
+// ============================================================================
+
+export interface Workspace {
+  activeBoardId: string | null;
+  boardOrder: string[];
+}
+
+// ============================================================================
+// Sprint (sprints/*.md) — legacy, kept for migration
 // ============================================================================
 
 export interface Sprint {
@@ -121,6 +155,16 @@ export interface Sprint {
   completed: number | null;
   issues: SprintIssueSummary[];
   path: string;
+  completedAt: string | null;
+  executionSummary: SprintExecutionSummary | null;
+}
+
+export interface SprintExecutionSummary {
+  totalIssues: number;
+  completedIssues: number;
+  failedIssues: number;
+  totalDuration: number;
+  waves: number;
 }
 
 export interface SprintIssueSummary {
@@ -153,6 +197,57 @@ export interface MilestoneEpicSummary {
   progress: string;
 }
 
+// ============================================================================
+// Review (sprint quality gate)
+// ============================================================================
+
+export interface ReviewResult {
+  issueId: string;
+  issueType: 'code' | 'non-code';
+  passed: boolean;
+  /** True when the review passed due to infrastructure failure, not genuine quality check */
+  autoPass?: boolean;
+  checks: ReviewCheck[];
+  reviewedAt: string;
+}
+
+export interface ReviewCheck {
+  name: string;
+  passed: boolean;
+  details: string;
+}
+
+// ============================================================================
+// Board Artifacts (board-scoped execution data)
+// ============================================================================
+
+export interface BoardArtifacts {
+  boardId: string;
+  progressLog: string;
+  outputFiles: string[];
+  reviewResults: ReviewResult[];
+  /** Log file names from boards/BOARD-NNN/logs/ (wave execution + review logs) */
+  executionLogs: string[];
+}
+
+/** @deprecated Use BoardArtifacts — kept for migration compatibility */
+export interface SprintArtifacts {
+  sprintId: string;
+  progressLog: string;
+  outputFiles: string[];
+  reviewResults: ReviewResult[];
+}
+
+// ============================================================================
+// Board full state (per-board data sent on board load)
+// ============================================================================
+
+export interface BoardFullState {
+  board: Board;
+  state: ProjectState;
+  issues: Issue[];
+}
+
 // ============================================================================
 // Plan full state (sent on planInit)
 // ============================================================================
@@ -160,6 +255,11 @@ export interface MilestoneEpicSummary {
 export interface PlanFullState {
   project: ProjectConfig;
   state: ProjectState;
+  boards: Board[];
+  workspace: Workspace;
+  // Active board's data (loaded eagerly for the focused tab)
+  activeBoard: BoardFullState | null;
+  // Legacy fields — populated during migration, normally empty
   issues: Issue[];
   sprints: Sprint[];
   milestones: Milestone[];