mstro-app 0.4.51 → 0.5.0

package/server/services/plan/issue-loader.ts

@@ -0,0 +1,64 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Issue loader: wraps parser.ts to load either board-scoped or
+ * project-level issues, emitting error/activation signals via callbacks
+ * so it stays decoupled from the EventEmitter in PlanExecutor.
+ */
+
+import { activateBoard } from './board-config.js';
+import type { WarnFn } from './issue-writer.js';
+import { parseBoardDirectory, parsePlanDirectory } from './parser.js';
+import type { Issue } from './types.js';
+
+export interface IssueLoaderHandlers {
+  /** Invoked when the board/project is in an unloadable state (not found, paused, etc.). */
+  onError: (message: string) => void;
+  /** Invoked to forward warnings from `activateBoard` side-effects. */
+  warn: WarnFn;
+}
+
+/**
+ * Load issues from a specific board, auto-activating draft boards.
+ * Returns null on error (and invokes `handlers.onError`).
+ */
+export async function loadBoardIssues(
+  pmDir: string,
+  boardId: string,
+  handlers: IssueLoaderHandlers,
+): Promise<Issue[] | null> {
+  const boardState = parseBoardDirectory(pmDir, boardId);
+  if (!boardState) {
+    handlers.onError(`Board not found: ${boardId}`);
+    return null;
+  }
+  if (boardState.state.paused) {
+    handlers.onError('Board is paused');
+    return null;
+  }
+  if (boardState.board.status === 'draft') {
+    await activateBoard(pmDir, boardId, handlers.warn);
+  } else if (boardState.board.status !== 'active') {
+    handlers.onError(`Board ${boardId} is not active (status: ${boardState.board.status})`);
+    return null;
+  }
+  return boardState.issues;
+}
+
+/** Load project-level issues (legacy or no boards). Returns null on error. */
+export function loadProjectIssues(
+  workingDir: string,
+  handlers: Pick<IssueLoaderHandlers, 'onError'>,
+): Issue[] | null {
+  const fullState = parsePlanDirectory(workingDir);
+  if (!fullState) {
+    handlers.onError('No PM directory found');
+    return null;
+  }
+  if (fullState.state.paused) {
+    handlers.onError('Project is paused');
+    return null;
+  }
+  return fullState.issues;
+}

package/server/services/plan/issue-writer.ts

@@ -0,0 +1,137 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Issue file mutations: front-matter status updates, activity note appends,
+ * stale-issue recovery, and wave-revert logic used by the plan executor.
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { checkAllAcceptanceCriteria, setFrontMatterFieldAsync } from './front-matter.js';
+import type { Issue } from './types.js';
+
+/** Emits a warning message — caller typically maps this to executor 'output' events. */
+export type WarnFn = (message: string, issueId?: string) => void;
+
+/** Matches the `status: <value>` front-matter line (YAML-style, first occurrence). */
+const STATUS_LINE_PATTERN = /^status:\s*(\S+)/m;
+
+/**
+ * Extract the `status:` front-matter value from an issue-file body. Returns
+ * `null` if the field is missing or malformed. Lives here alongside the other
+ * front-matter mutators so all modules parse the status identically.
+ */
+export function extractIssueStatus(content: string): string | null {
+  return content.match(STATUS_LINE_PATTERN)?.[1] ?? null;
+}
+
+/**
+ * Resolve an issue's relative path against a base directory, ensuring it
+ * stays inside the base (guards against `..` and absolute-path escapes).
+ */
+export function validateIssuePath(issuePath: string, baseDir: string): string {
+  const resolvedBase = resolve(baseDir);
+  const resolvedFull = resolve(resolvedBase, issuePath);
+  const rel = relative(resolvedBase, resolvedFull);
+  if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`Invalid issue path: path traversal detected in "${issuePath}"`);
+  }
+  return resolvedFull;
+}
+
+/**
+ * Update an issue's `status:` front-matter field, and — when transitioning
+ * to `done` — check off any remaining acceptance-criteria checkboxes.
+ */
+export async function updateIssueFrontMatter(
+  pmDir: string,
+  issuePath: string,
+  newStatus: string,
+  warn: WarnFn,
+): Promise<void> {
+  try {
+    const fullPath = validateIssuePath(issuePath, pmDir);
+    await setFrontMatterFieldAsync(fullPath, 'status', newStatus);
+
+    if (newStatus === 'done') {
+      const content = await readFile(fullPath, 'utf-8');
+      const updated = checkAllAcceptanceCriteria(content);
+      if (updated !== content) await writeFile(fullPath, updated, 'utf-8');
+    }
+  } catch (err) {
+    warn(`Warning: failed to update issue front matter for ${issuePath}: ${errMsg(err)}`);
+  }
+}
+
+/**
+ * After a wave fails, revert any issue still stuck in `in_progress` back to
+ * its pre-wave status. Silently skips issues already out of `in_progress`.
+ */
+export async function revertIncompleteIssues(
+  pmDir: string,
+  issues: Issue[],
+  warn: WarnFn,
+): Promise<void> {
+  for (const issue of issues) {
+    const fullPath = validateIssuePath(issue.path, pmDir);
+    try {
+      const content = await readFile(fullPath, 'utf-8');
+      if (extractIssueStatus(content) === 'in_progress') {
+        await updateIssueFrontMatter(pmDir, issue.path, issue.status, warn);
+      }
+    } catch (err) {
+      warn(`Warning: failed to revert issue status: ${errMsg(err)}`, issue.id);
+    }
+  }
+}
+
+/** Append a cancellation note to the issue's `## Activity` section. */
+export async function appendCancellationNote(
+  pmDir: string,
+  issue: Issue,
+  reason: string,
+  warn: WarnFn,
+): Promise<void> {
+  const fullPath = validateIssuePath(issue.path, pmDir);
+  try {
+    let content = await readFile(fullPath, 'utf-8');
+    const entry = `- Cancelled (${new Date().toISOString().split('T')[0]}): ${reason}`;
+    if (content.includes('## Activity')) {
+      content = content.replace(/## Activity/, `## Activity\n${entry}`);
+    } else {
+      content += `\n\n## Activity\n${entry}`;
+    }
+    await writeFile(fullPath, content, 'utf-8');
+  } catch (err) {
+    warn(`Warning: failed to append cancellation note: ${errMsg(err)}`, issue.id);
+  }
+}
+
+/**
+ * Recover from a previous interrupted execution by reverting stale
+ * `in_progress` and `in_review` issues back to `todo`. Returns the list of
+ * recovered issue descriptors (e.g. "FEAT-012 (in_progress → todo)") so the
+ * caller can emit a single summary event.
+ */
+export async function recoverStaleIssues(
+  pmDir: string,
+  issues: Issue[],
+  warn: WarnFn,
+): Promise<string[]> {
+  const staleStatuses = new Set(['in_progress', 'in_review']);
+  const recovered: string[] = [];
+
+  for (const issue of issues) {
+    if (issue.type === 'epic') continue;
+    if (staleStatuses.has(issue.status)) {
+      await updateIssueFrontMatter(pmDir, issue.path, 'todo', warn);
+      recovered.push(`${issue.id} (${issue.status} → todo)`);
+    }
+  }
+  return recovered;
+}
+
+function errMsg(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

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

@@ -9,6 +9,7 @@
 
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { extractIssueStatus } from './issue-writer.js';
 import { defaultPmDir, resolvePmDir } from './parser.js';
 import type { Issue } from './types.js';
 
@@ -90,7 +91,7 @@ function publishSingleOutput(
   // Only publish for confirmed-done issues
   try {
     const content = readFileSync(join(pmDir, issue.path), 'utf-8');
-    if (!content.match(/^status:\s*done$/m)) return;
+    if (extractIssueStatus(content) !== 'done') return;
   } catch { return; }
 
   const srcPath = resolveOutputPath(issue, workingDir, sprintSandboxDir);

package/server/services/plan/progress-log.ts

@@ -0,0 +1,92 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Progress log writer: ensures output directories exist and appends
+ * per-wave markdown entries to the board or PM-dir progress.md.
+ */
+
+import { existsSync } from 'node:fs';
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { validateIssuePath, type WarnFn } from './issue-writer.js';
+import type { Issue } from './types.js';
+
+/** Create the board's or PM dir's `out/` directory if it doesn't exist. */
+export async function ensureOutputDirs(pmDir: string | null, boardDir: string | null): Promise<void> {
+  if (boardDir) {
+    const boardOutDir = join(boardDir, 'out');
+    if (!existsSync(boardOutDir)) await mkdir(boardOutDir, { recursive: true });
+    return;
+  }
+  if (pmDir) {
+    const outDir = join(pmDir, 'out');
+    if (!existsSync(outDir)) await mkdir(outDir, { recursive: true });
+  }
+}
+
+/**
+ * Append a wave summary section to progress.md (creating the file with a
+ * `# Board Progress` header if missing). Reads each issue's on-disk status
+ * to partition completed vs failed.
+ */
+export async function appendProgressEntry(
+  pmDir: string | null,
+  boardDir: string | null,
+  issues: Issue[],
+  waveStart: number,
+  warn: WarnFn,
+): Promise<void> {
+  if (!pmDir) return;
+
+  const progressPath = boardDir ? join(boardDir, 'progress.md') : join(pmDir, 'progress.md');
+  const durationMin = Math.round((Date.now() - waveStart) / 60_000);
+  const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 16);
+
+  const { completed, failed } = await partitionByOnDiskStatus(pmDir, issues);
+
+  const lines = [
+    '',
+    `## ${timestamp} — Wave [${issues.map(i => i.id).join(', ')}]`,
+    '',
+    `- **Duration**: ${durationMin} min`,
+    `- **Completed**: ${completed.length}/${issues.length}${completed.length > 0 ? ` (${completed.join(', ')})` : ''}`,
+  ];
+  if (failed.length > 0) {
+    lines.push(`- **Failed**: ${failed.join(', ')}`);
+  }
+  lines.push('');
+
+  await writeProgressLines(progressPath, lines, warn);
+}
+
+async function partitionByOnDiskStatus(
+  pmDir: string,
+  issues: Issue[],
+): Promise<{ completed: string[]; failed: string[] }> {
+  const completed: string[] = [];
+  const failed: string[] = [];
+  for (const issue of issues) {
+    try {
+      const content = await readFile(validateIssuePath(issue.path, pmDir), 'utf-8');
+      const statusMatch = content.match(/^status:\s*(\S+)/m);
+      if (statusMatch?.[1] === 'done') completed.push(issue.id);
+      else failed.push(issue.id);
+    } catch {
+      failed.push(issue.id);
+    }
+  }
+  return { completed, failed };
+}
+
+async function writeProgressLines(filePath: string, lines: string[], warn: WarnFn): Promise<void> {
+  try {
+    if (existsSync(filePath)) {
+      await appendFile(filePath, `\n${lines.join('\n')}`, 'utf-8');
+    } else {
+      await writeFile(filePath, `# Board Progress\n${lines.join('\n')}`, 'utf-8');
+    }
+  } catch (err) {
+    warn(`Warning: failed to write progress log: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}

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

@@ -28,23 +28,40 @@ export interface CoordinatorPromptOptions {
  */
 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 outDir = resolveOutDir(workingDir, pmDir, boardDir);
+  const teamName = `pm-wave-${Date.now()}`;
+
+  const issueBlocks = issues.map(issue => buildIssueBlock(issue, existingDocs, resolveOutputPath)).join('\n\n---\n\n');
+  const teammateSpawns = issues.map(issue => buildTeammateSpawn(issue, teamName, pmDir, existingDocs, resolveOutputPath)).join('\n\n');
+
+  return assembleCoordinatorPrompt({ issues, workingDir, pmDir, outDir, teamName, issueBlocks, teammateSpawns });
+}
+
+function resolveOutDir(workingDir: string, pmDir: string | null, boardDir: string | null): string {
+  if (boardDir) return join(boardDir, 'out');
+  if (pmDir) return join(pmDir, 'out');
+  return join(workingDir, '.mstro', 'pm', 'out');
+}
 
-  const issueBlocks = issues.map(issue => {
-    const criteria = issue.acceptanceCriteria
-      .map(c => `- [${c.checked ? 'x' : ' '}] ${c.text}`)
-      .join('\n');
+function buildIssueBlock(
+  issue: Issue,
+  existingDocs: string[],
+  resolveOutputPath: (issue: Issue) => string,
+): string {
+  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 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')}`
-      : '';
+  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}
+  return `### ${issue.id}: ${issue.title}
 
 **Type**: ${issue.type} | **Priority**: ${issue.priority} | **Estimate**: ${issue.estimate ?? 'unestimated'}
 
@@ -59,32 +76,53 @@ ${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()}"\`:
+function buildTeammateSpawn(
+  issue: Issue,
+  teamName: string,
+  pmDir: string | null,
+  existingDocs: string[],
+  resolveOutputPath: (issue: Issue) => string,
+): string {
+  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');
+}
+
+interface AssembleArgs {
+  issues: Issue[];
+  workingDir: string;
+  pmDir: string | null;
+  outDir: string;
+  teamName: string;
+  issueBlocks: string;
+  teammateSpawns: string;
+}
+
+function assembleCoordinatorPrompt(args: AssembleArgs): string {
+  const { issues, workingDir, pmDir, outDir, teamName, issueBlocks, teammateSpawns } = args;
+  const issueCount = issues.length;
+  const plural = issueCount > 1 ? 's' : '';
+  const checklist = issues.map(i => `- [ ] ${i.id.toLowerCase()}`).join('\n');
+  const teammateNames = issues.map(i => `- \`${i.id.toLowerCase()}\``).join('\n');
 
-  return `You are the team lead coordinating ${issues.length} issue${issues.length > 1 ? 's' : ''} using Agent Teams.
+  return `You are the team lead coordinating ${issueCount} issue${plural} using Agent Teams.
 
 ## Project Directory
 Working directory: ${workingDir}
@@ -102,7 +140,7 @@ All team coordination uses exactly two tools:
 
 ### 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.
+Send a single message containing ${issueCount} **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}
 
@@ -113,10 +151,10 @@ After spawning, idle notifications arrive automatically as messages — you will
 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')}
+${checklist}
 
 Exact teammate names for SendMessage (messages to any other name are silently dropped):
-${issues.map(i => `- \`${i.id.toLowerCase()}\``).join('\n')}
+${teammateNames}
 
 When you receive an idle notification from a teammate:
 - Check off that teammate in the checklist above
@@ -143,7 +181,7 @@ After all outputs are verified:
 ## 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.
+- Wait for idle notifications from all ${issueCount} 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.

package/server/services/plan/readiness-planner.ts

@@ -0,0 +1,50 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Pure helpers for wave readiness: human-readable completion reasons
+ * and detection of "dead" issues stuck in non-terminal states.
+ */
+
+import type { Issue } from './types.js';
+
+const TERMINAL_STATUSES = new Set(['done', 'cancelled']);
+
+/** Build the user-facing completion message shown when no issues remain. */
+export function buildCompletionReason(issues: Issue[], epicScope: string | null): string {
+  const nonEpic = issues.filter(i => i.type !== 'epic');
+  const done = nonEpic.filter(i => TERMINAL_STATUSES.has(i.status)).length;
+  const blocked = nonEpic.filter(i => i.status === 'todo').length;
+  if (done === nonEpic.length) return epicScope ? 'All epic issues are done' : 'All issues are done';
+  if (blocked > 0) return `${done}/${nonEpic.length} issues done, ${blocked} blocked by incomplete dependencies`;
+  return epicScope ? 'All epic issues are done or blocked' : 'All work is done or blocked';
+}
+
+/**
+ * Detect issues stuck in non-terminal states with no path to completion.
+ * Returns a human-readable reason, or null when the board is healthy.
+ */
+export function detectDeadState(issues: Issue[]): string | null {
+  const nonEpic = issues.filter(i => i.type !== 'epic');
+  const stuck = nonEpic.filter(i => !TERMINAL_STATUSES.has(i.status) && i.status !== 'todo');
+  if (stuck.length === 0) return null;
+
+  const stuckIds = stuck.map(i => `${i.id} (${i.status})`).join(', ');
+
+  const issueByPath = new Map(issues.map(i => [i.path, i]));
+  const blockedByStuck = nonEpic.filter(i => {
+    if (i.status !== 'todo') return false;
+    return i.blockedBy.some(bp => {
+      const blocker = issueByPath.get(bp);
+      return blocker && !TERMINAL_STATUSES.has(blocker.status);
+    });
+  });
+  const blockedIds = blockedByStuck.map(i => i.id).join(', ');
+
+  return `Board stuck: ${stuckIds} cannot progress${blockedIds ? `. Blocking: ${blockedIds}` : ''}`;
+}
+
+/** True iff any non-epic issue is stuck in a non-terminal, non-todo state. */
+export function hasBlockedIssues(issues: Issue[]): boolean {
+  return issues.some(i => i.type !== 'epic' && !TERMINAL_STATUSES.has(i.status) && i.status !== 'todo');
+}

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

@@ -13,16 +13,19 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import { join } from 'node:path';
 import { ResilientRunner } from '../../cli/headless/resilient-runner.js';
 import { loadAgentPrompt } from './agent-loader.js';
+import { getBoardReviewCriteria, resolveActiveBoardId } from './board-config.js';
 import { resolveIsCodeTask } from './issue-classification.js';
+import { appendCancellationNote, type WarnFn } from './issue-writer.js';
+import { resolveOutputPath } from './output-manager.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) */
+/** Review runner stall timeouts (ms) — hard cap is a backstop that only fires after stall signals flag the run */
 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
+const REVIEW_STALL_HARD_CAP_MS = 2_700_000; // 45 min backstop
 
 export interface ReviewIssueOptions {
   workingDir: string;
@@ -244,3 +247,100 @@ function buildReviewPrompt(
   return `You are a reviewer. Review the work done for issue ${issue.id}: ${issue.title}.\n\n## Acceptance Criteria\n${criteriaStr}\n\nOutput EXACTLY one JSON object on its own line (no markdown fencing):\n{"passed": true, "checks": [{"name": "criteria_met", "passed": true, "details": "..."}]}`;
 }
 
+// ── Review pipeline orchestration ───────────────────────────
+
+/** Status messages emitted during the review pipeline. */
+export type ReviewProgressStatus = 'reviewing' | 'passed' | 'failed' | 'max_attempts';
+
+/** Callbacks for the executor to observe review pipeline events. */
+export interface ReviewPipelineCallbacks {
+  /** Update an issue's front-matter status on disk. */
+  setStatus: (issuePath: string, status: string) => Promise<void>;
+  onOutput: (issueId: string, text: string) => void;
+  onReviewProgress: (issueId: string, status: ReviewProgressStatus) => void;
+  onIssueAbandoned: (issueId: string, reason: string, attempts: number) => void;
+  onIssueCompleted: (issue: Issue) => void;
+  onIssueError: (issueId: string, error: string) => void;
+  warn: WarnFn;
+}
+
+/** Configuration for running the full review pipeline for a single issue. */
+export interface ReviewPipelineOptions {
+  issue: Issue;
+  pmDir: string;
+  workingDir: string;
+  executionDir: string | null;
+  boardDir: string | null;
+  boardId: string | null;
+  extraEnv?: Record<string, string>;
+}
+
+/**
+ * Full review pipeline for a completed issue: attempt-count guard, status
+ * transitions, AI review, persistence, and event emission through the
+ * caller's callbacks. Returns `true` when the review passes and the issue is
+ * marked `done`, `false` otherwise (reverted, cancelled, or errored).
+ */
+export async function runReviewPipeline(
+  options: ReviewPipelineOptions,
+  callbacks: ReviewPipelineCallbacks,
+): Promise<boolean> {
+  const { issue, pmDir, workingDir, executionDir, boardDir, boardId, extraEnv } = options;
+  const reviewDir = boardDir ?? pmDir;
+  const attempts = getReviewAttemptCount(reviewDir, issue);
+
+  if (attempts >= MAX_REVIEW_ATTEMPTS) {
+    await callbacks.setStatus(issue.path, 'cancelled');
+    await appendCancellationNote(
+      pmDir,
+      issue,
+      `Cancelled after ${MAX_REVIEW_ATTEMPTS} failed reviews — issue may need restructuring`,
+      callbacks.warn,
+    );
+    callbacks.onReviewProgress(issue.id, 'max_attempts');
+    callbacks.onIssueAbandoned(
+      issue.id,
+      `Review failed ${MAX_REVIEW_ATTEMPTS} times — cancelled to unblock dependents`,
+      attempts,
+    );
+    callbacks.onOutput(issue.id, 'Review: max attempts reached, cancelling issue to unblock dependents');
+    return false;
+  }
+
+  await callbacks.setStatus(issue.path, 'in_review');
+  callbacks.onReviewProgress(issue.id, 'reviewing');
+
+  const outputPath = resolveOutputPath(issue, workingDir, boardDir);
+  const effectiveBoardId = boardId ?? resolveActiveBoardId(pmDir);
+  const reviewCriteria = await getBoardReviewCriteria(pmDir, effectiveBoardId, callbacks.warn);
+
+  const result = await reviewIssue({
+    workingDir: executionDir || workingDir,
+    issue,
+    pmDir,
+    outputPath,
+    onOutput: (text) => callbacks.onOutput(issue.id, text),
+    logDir: boardDir ? join(boardDir, 'logs') : undefined,
+    reviewCriteria,
+    boardDir,
+    extraEnv,
+  });
+  persistReviewResult(reviewDir, issue, result);
+
+  if (result.passed) {
+    await callbacks.setStatus(issue.path, 'done');
+    callbacks.onReviewProgress(issue.id, 'passed');
+    callbacks.onIssueCompleted(issue);
+    return true;
+  }
+
+  await callbacks.setStatus(issue.path, 'todo');
+  appendReviewFeedback(pmDir, issue, result);
+  callbacks.onReviewProgress(issue.id, 'failed');
+  callbacks.onIssueError(
+    issue.id,
+    `Review failed: ${result.checks.filter(c => !c.passed).map(c => c.name).join(', ')}`,
+  );
+  return false;
+}
+