mstro-app 0.4.1 → 0.4.3

package/dist/server/services/plan/executor.js

@@ -3,25 +3,51 @@
 /**
  * Plan Executor — Wave-based execution with Claude Code Agent Teams.
  *
- * Reads the dependency DAG from .pm/, picks ALL unblocked issues per wave,
- * spawns a coordinator Claude session that uses Agent Teams to execute them
- * in parallel, then reconciles state and repeats for newly-unblocked issues.
+ * Orchestrates the execution loop: picks ready issues, executes waves,
+ * runs AI review gate, reconciles state, and repeats.
+ *
+ * Implementation is split across focused modules:
+ * - config-installer.ts  — teammate permissions + bouncer MCP install/uninstall
+ * - prompt-builder.ts    — Agent Teams coordinator prompt construction
+ * - output-manager.ts    — output path resolution, listing, publishing
+ * - review-gate.ts       — AI-powered quality gate (review, parse, persist)
+ * - front-matter.ts      — YAML front matter field editing utility
  */
 import { EventEmitter } from 'node:events';
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { existsSync, mkdirSync, 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 { generateMcpConfig } from '../../cli/headless/mcp-config.js';
+import { ConfigInstaller } from './config-installer.js';
 import { resolveReadyToWork } from './dependency-resolver.js';
-import { parsePlanDirectory, resolvePmDir } from './parser.js';
+import { replaceFrontMatterField, setFrontMatterField } from './front-matter.js';
+import { listExistingDocs, publishOutputs, resolveOutputPath } from './output-manager.js';
+import { parseBoardDirectory, parsePlanDirectory, resolvePmDir } from './parser.js';
+import { buildCoordinatorPrompt } from './prompt-builder.js';
+import { appendReviewFeedback, getReviewAttemptCount, MAX_REVIEW_ATTEMPTS, persistReviewResult, reviewIssue } from './review-gate.js';
 import { reconcileState } from './state-reconciler.js';
+/** Max teammates per wave. Agent Teams docs recommend 3-5; beyond 5-6 returns diminish. */
+const MAX_WAVE_SIZE = 5;
+/** Stop after this many consecutive waves with zero completions. */
+const MAX_CONSECUTIVE_EMPTY_WAVES = 3;
+/** Wave execution stall timeouts (ms) */
+const WAVE_STALL_WARNING_MS = 1_800_000; // 30 min — Agent Teams leads are silent while teammates work
+const WAVE_STALL_KILL_MS = 3_600_000; // 60 min — waves run longer
+const WAVE_STALL_HARD_CAP_MS = 7_200_000; // 2 hr hard cap
+const WAVE_STALL_MAX_EXTENSIONS = 10;
 export class PlanExecutor extends EventEmitter {
     status = 'idle';
     workingDir;
     shouldStop = false;
     shouldPause = false;
     epicScope = null;
+    /** Board directory path (e.g. /path/.pm/boards/BOARD-001). Used for outputs, reviews, progress. */
+    boardDir = null;
+    /** Board ID being executed (e.g. "BOARD-001") */
+    boardId = null;
+    configInstaller;
+    /** Flag to prevent start() from clearing scope set by startBoard/startEpic */
+    _scopeSetByCall = false;
     metrics = {
         issuesCompleted: 0,
         issuesAttempted: 0,
@@ -32,15 +58,19 @@ export class PlanExecutor extends EventEmitter {
     constructor(workingDir) {
         super();
         this.workingDir = workingDir;
+        this.configInstaller = new ConfigInstaller(workingDir);
     }
-    getStatus() {
-        return this.status;
-    }
-    getMetrics() {
-        return { ...this.metrics };
-    }
+    getStatus() { return this.status; }
+    getMetrics() { return { ...this.metrics }; }
     async startEpic(epicPath) {
         this.epicScope = epicPath;
+        this._scopeSetByCall = true;
+        return this.start();
+    }
+    /** Start execution, optionally scoped to a specific board. */
+    async startBoard(boardId) {
+        this.boardId = boardId;
+        this._scopeSetByCall = true;
         return this.start();
     }
     async start() {
@@ -48,29 +78,25 @@ export class PlanExecutor extends EventEmitter {
             return;
         this.shouldStop = false;
         this.shouldPause = false;
+        // Reset scoping from previous runs unless explicitly set by startBoard/startEpic
+        if (!this._scopeSetByCall) {
+            this.epicScope = null;
+            this.boardId = null;
+        }
+        this._scopeSetByCall = false;
         this.status = 'starting';
         this.emit('statusChanged', this.status);
         const startTime = Date.now();
-        try {
-            this.status = 'executing';
-            this.emit('statusChanged', this.status);
-            while (!this.shouldStop && !this.shouldPause) {
-                const readyIssues = this.pickReadyIssues();
-                if (readyIssues.length === 0)
-                    break;
-                // Always use wave execution with Agent Teams — even for single issues.
-                // Each teammate runs as a separate process with its own context window,
-                // bouncer coverage via .mcp.json + PreToolUse hook, and disk persistence.
-                await this.executeWave(readyIssues);
-            }
-        }
-        catch (error) {
+        this.status = 'executing';
+        this.emit('statusChanged', this.status);
+        this.boardDir = this.resolveBoardDir();
+        const stallResult = await this.runWaveLoop();
+        this.metrics.totalDuration = Date.now() - startTime;
+        if (stallResult === 'stalled') {
             this.status = 'error';
-            this.emit('error', error instanceof Error ? error.message : String(error));
-            return;
+            this.emit('error', `Execution stalled: ${MAX_CONSECUTIVE_EMPTY_WAVES} consecutive waves completed zero issues. Issues may be stuck in review or failing repeatedly.`);
         }
-        this.metrics.totalDuration = Date.now() - startTime;
-        if (this.shouldPause) {
+        else if (this.shouldPause) {
             this.status = 'paused';
         }
         else if (this.shouldStop) {
@@ -81,52 +107,72 @@ export class PlanExecutor extends EventEmitter {
         }
         this.emit('statusChanged', this.status);
     }
-    pause() {
-        this.shouldPause = true;
-    }
-    stop() {
-        this.shouldStop = true;
+    /** Run waves until done, paused, stopped, or stalled. Returns 'stalled' if zero-completion cap hit. */
+    async runWaveLoop() {
+        let consecutiveZeroCompletions = 0;
+        while (!this.shouldStop && !this.shouldPause) {
+            const readyIssues = this.pickReadyIssues();
+            if (readyIssues.length === 0)
+                break;
+            const completedCount = await this.executeWave(readyIssues.slice(0, MAX_WAVE_SIZE));
+            if (completedCount > 0) {
+                consecutiveZeroCompletions = 0;
+                continue;
+            }
+            consecutiveZeroCompletions++;
+            if (consecutiveZeroCompletions >= MAX_CONSECUTIVE_EMPTY_WAVES)
+                return 'stalled';
+        }
+        return 'done';
     }
+    pause() { this.shouldPause = true; }
+    stop() { this.shouldStop = true; }
     resume() {
         if (this.status !== 'paused')
             return Promise.resolve();
         this.shouldPause = false;
+        // Preserve board/epic scope across resume by marking as a scoped call
+        this._scopeSetByCall = true;
         return this.start();
     }
-    // ── Wave execution (Agent Teams) ──────────────────────────────
+    // ── Wave execution ───────────────────────────────────────────
     async executeWave(issues) {
         const waveStart = Date.now();
         const waveIds = issues.map(i => i.id);
+        const waveLabel = `wave[${waveIds.join(',')}]`;
         this.metrics.currentWaveIds = waveIds;
         this.metrics.issuesAttempted += issues.length;
         this.emit('waveStarted', { issueIds: waveIds });
-        // Ensure .pm/out/ exists for execution output
-        const pmDir = resolvePmDir(this.workingDir);
-        if (pmDir) {
-            const outDir = join(pmDir, 'out');
-            if (!existsSync(outDir))
-                mkdirSync(outDir, { recursive: true });
-        }
-        // Pre-approve tools so teammates don't hit interactive permission prompts
-        this.installTeammatePermissions();
-        // Install bouncer .mcp.json so Agent Teams teammates discover it
-        this.installBouncerForSubagents();
-        // Mark all wave issues as in_progress
+        this.ensureOutputDirs();
+        this.configInstaller.installTeammatePermissions();
+        this.configInstaller.installBouncerForSubagents();
         for (const issue of issues) {
             this.updateIssueFrontMatter(issue.path, 'in_progress');
         }
-        const prompt = this.buildCoordinatorPrompt(issues);
+        const existingDocs = listExistingDocs(this.workingDir, this.boardDir);
+        const pmDir = resolvePmDir(this.workingDir);
+        const prompt = buildCoordinatorPrompt({
+            issues,
+            workingDir: this.workingDir,
+            pmDir,
+            boardDir: this.boardDir,
+            existingDocs,
+            resolveOutputPath: (issue) => resolveOutputPath(issue, this.workingDir, this.boardDir),
+        });
+        let completedCount = 0;
         try {
             const runner = new HeadlessRunner({
                 workingDir: this.workingDir,
                 directPrompt: prompt,
-                stallKillMs: 3_600_000, // 60 min — waves run longer
-                stallHardCapMs: 7_200_000, // 2 hr hard cap
-                extraEnv: {
-                    CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1',
-                },
+                stallWarningMs: WAVE_STALL_WARNING_MS,
+                stallKillMs: WAVE_STALL_KILL_MS,
+                stallHardCapMs: WAVE_STALL_HARD_CAP_MS,
+                stallMaxExtensions: WAVE_STALL_MAX_EXTENSIONS,
+                verbose: process.env.MSTRO_VERBOSE === '1',
+                disallowedTools: ['TeamCreate', 'TeamDelete', 'TaskCreate', 'TaskUpdate', 'TaskList'],
+                extraEnv: { CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1' },
                 outputCallback: (text) => {
-                    this.emit('output', { issueId: `wave[${waveIds.join(',')}]`, text });
+                    this.emit('output', { issueId: waveLabel, text });
                 },
             });
             const result = await runWithFileLogger('pm-execute-wave', () => runner.run());
@@ -136,8 +182,7 @@ export class PlanExecutor extends EventEmitter {
                     error: result.error || 'Wave did not complete successfully',
                 });
             }
-            // Check which issues the agents actually completed by reading disk
-            this.reconcileWaveResults(issues);
+            completedCount = await this.reconcileWaveResults(issues);
         }
         catch (error) {
             this.emit('waveError', {
@@ -147,29 +192,60 @@ export class PlanExecutor extends EventEmitter {
             this.revertIncompleteIssues(issues);
         }
         finally {
-            // Clean up temporary configs — must run even if wave throws
-            this.uninstallBouncerForSubagents();
-            this.uninstallTeammatePermissions();
-        }
-        // Reconcile STATE.md and sprint statuses after wave
-        reconcileState(this.workingDir);
-        this.emit('stateUpdated');
-        // Copy confirmed-done outputs to user-specified output_file paths
-        this.publishOutputs(issues);
-        // Append progress log entry
-        this.appendProgressEntry(issues, waveStart);
+            this.configInstaller.uninstallBouncerForSubagents();
+            this.configInstaller.uninstallTeammatePermissions();
+        }
+        this.finalizeWave(issues, waveStart, waveLabel);
         this.metrics.currentWaveIds = [];
+        return completedCount;
+    }
+    /**
+     * Post-wave operations wrapped individually so a failure in one
+     * doesn't prevent the others or kill the while loop in start().
+     */
+    finalizeWave(issues, waveStart, waveLabel) {
+        try {
+            reconcileState(this.workingDir, this.boardId ?? undefined);
+            this.emit('stateUpdated');
+        }
+        catch (err) {
+            this.emit('output', {
+                issueId: waveLabel,
+                text: `Warning: state reconciliation failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        try {
+            publishOutputs(issues, this.workingDir, this.boardDir, {
+                onWarning: (issueId, text) => this.emit('output', { issueId, text: `Warning: ${text}` }),
+            });
+        }
+        catch (err) {
+            this.emit('output', {
+                issueId: waveLabel,
+                text: `Warning: output publishing failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        try {
+            this.appendProgressEntry(issues, waveStart);
+        }
+        catch (err) {
+            this.emit('output', {
+                issueId: waveLabel,
+                text: `Warning: progress log update failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
     }
+    // ── Review gate orchestration ────────────────────────────────
     /**
-     * After a wave, check each issue's status on disk.
-     * `status: done` in issue front matter is the single completion signal.
-     * Output doc existence is NOT used as a proxy — code-focused issues
-     * (bug fixes, refactors) don't produce docs but are still valid completions.
+     * After a wave, check each issue's status on disk and run the AI review gate.
+     * Issues that agents marked as `done` are moved to `in_review`, reviewed,
+     * and either confirmed `done` (passed) or reverted to `todo` (failed).
      */
-    reconcileWaveResults(issues) {
+    async reconcileWaveResults(issues) {
         const pmDir = resolvePmDir(this.workingDir);
         if (!pmDir)
-            return;
+            return 0;
+        let completed = 0;
         for (const issue of issues) {
             const fullPath = join(pmDir, issue.path);
             try {
@@ -177,11 +253,17 @@ export class PlanExecutor extends EventEmitter {
                 const statusMatch = content.match(/^status:\s*(\S+)/m);
                 const currentStatus = statusMatch?.[1] ?? 'unknown';
                 if (currentStatus === 'done') {
-                    this.metrics.issuesCompleted++;
-                    this.emit('issueCompleted', issue);
+                    if (issue.reviewGate === 'none') {
+                        // Skip review gate — accept agent's done status directly
+                        this.metrics.issuesCompleted++;
+                        this.emit('issueCompleted', issue);
+                        completed++;
+                    }
+                    else {
+                        completed += await this.runReviewGate(issue, pmDir);
+                    }
                 }
                 else {
-                    // Not done — revert to prior status
                     this.updateIssueFrontMatter(issue.path, issue.status);
                     this.emit('issueError', {
                         issueId: issue.id,
@@ -193,414 +275,191 @@ export class PlanExecutor extends EventEmitter {
                 this.emit('issueError', { issueId: issue.id, error: 'Could not read issue file after wave' });
             }
         }
+        return completed;
+    }
+    /** Run the review gate for a single issue that agents marked as done. Returns 1 if passed, 0 otherwise. */
+    async runReviewGate(issue, pmDir) {
+        const reviewDir = this.boardDir ?? pmDir;
+        const attempts = getReviewAttemptCount(reviewDir, issue);
+        if (attempts >= MAX_REVIEW_ATTEMPTS) {
+            this.updateIssueFrontMatter(issue.path, 'in_review');
+            this.emit('reviewProgress', { issueId: issue.id, status: 'max_attempts' });
+            this.emit('output', { issueId: issue.id, text: 'Review: max attempts reached, keeping in review' });
+            return 0;
+        }
+        this.updateIssueFrontMatter(issue.path, 'in_review');
+        this.emit('reviewProgress', { issueId: issue.id, status: 'reviewing' });
+        const outputPath = resolveOutputPath(issue, this.workingDir, this.boardDir);
+        const result = await reviewIssue({
+            workingDir: this.workingDir,
+            issue,
+            pmDir,
+            outputPath,
+            onOutput: (text) => this.emit('output', { issueId: issue.id, text }),
+        });
+        persistReviewResult(reviewDir, issue, result);
+        if (result.passed) {
+            this.updateIssueFrontMatter(issue.path, 'done');
+            this.metrics.issuesCompleted++;
+            this.emit('reviewProgress', { issueId: issue.id, status: 'passed' });
+            this.emit('issueCompleted', issue);
+            return 1;
+        }
+        this.updateIssueFrontMatter(issue.path, 'todo');
+        appendReviewFeedback(pmDir, issue, result);
+        this.emit('reviewProgress', { issueId: issue.id, status: 'failed' });
+        this.emit('issueError', {
+            issueId: issue.id,
+            error: `Review failed: ${result.checks.filter(c => !c.passed).map(c => c.name).join(', ')}`,
+        });
+        return 0;
     }
-    // ── Issue picking ─────────────────────────────────────────────
+    // ── Helpers ──────────────────────────────────────────────────
     pickReadyIssues() {
-        const fullState = parsePlanDirectory(this.workingDir);
-        if (!fullState) {
-            this.emit('error', 'No .pm/ directory found');
+        const pmDir = resolvePmDir(this.workingDir);
+        if (!pmDir) {
+            this.emit('error', 'No PM directory found');
             return [];
         }
-        if (fullState.state.paused) {
-            this.emit('error', 'Project is paused');
+        const effectiveBoardId = this.boardId ?? this.resolveActiveBoardId();
+        const issues = effectiveBoardId
+            ? this.loadBoardIssues(pmDir, effectiveBoardId)
+            : this.loadProjectIssues();
+        if (!issues)
             return [];
-        }
-        const readyIssues = resolveReadyToWork(fullState.issues, this.epicScope ?? undefined);
+        const readyIssues = resolveReadyToWork(issues, this.epicScope ?? undefined);
         if (readyIssues.length === 0) {
             this.emit('complete', this.epicScope ? 'All epic issues are done or blocked' : 'All work is done or blocked');
+            if (effectiveBoardId) {
+                this.tryCompleteBoardIfDone(pmDir, effectiveBoardId, issues);
+            }
         }
         return readyIssues;
     }
-    // ── Prompt building ───────────────────────────────────────────
-    /**
-     * Build the team lead prompt for a wave of issues.
-     * Uses Agent Teams for true parallel execution as separate processes —
-     * each teammate gets its own context window and sends idle notifications
-     * when done. The team is created implicitly by the first Agent(team_name=...) call.
-     */
-    buildCoordinatorPrompt(issues) {
-        const pmDir = resolvePmDir(this.workingDir);
-        const outDir = pmDir ? join(pmDir, 'out') : join(this.workingDir, '.pm', 'out');
-        // Collect existing output docs that issues may need as input
-        const existingDocs = this.listExistingDocs();
-        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')}`
-                : '';
-            // Find predecessor output docs this issue should read
-            const predecessorDocs = issue.blockedBy
-                .map(bp => {
-                const blockerId = bp.replace(/^backlog\//, '').replace(/\.md$/, '');
-                return existingDocs.find(d => d.toLowerCase().includes(blockerId.toLowerCase()));
-            })
-                .filter(Boolean);
-            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**: ${this.resolveOutputPath(issue)}`;
-        }).join('\n\n---\n\n');
-        const teamName = `pm-wave-${Date.now()}`;
-        const teammateSpawns = issues.map(issue => {
-            const predecessorDocs = issue.blockedBy
-                .map(bp => {
-                const blockerId = bp.replace(/^backlog\//, '').replace(/\.md$/, '');
-                return existingDocs.find(d => d.toLowerCase().includes(blockerId.toLowerCase()));
-            })
-                .filter(Boolean);
-            const predInstr = predecessorDocs.length > 0
-                ? `Read these predecessor output docs before starting: ${predecessorDocs.join(', ')}. `
-                : '';
-            const outputFile = this.resolveOutputPath(issue);
-            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.
-> CRITICAL: Write ALL output/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\`.
-> Do not modify STATE.md. Do not work on anything outside this issue's scope.`;
-        }).join('\n\n');
-        return `You are the team lead coordinating ${issues.length} issue${issues.length > 1 ? 's' : ''} using Agent Teams.
-
-## Project Directory
-Working directory: ${this.workingDir}
-Plan directory: ${pmDir || '.pm/'}
-
-## Issues to Execute
-
-${issueBlocks}
-
-## Execution Protocol — Agent Teams
-
-### Step 1: Spawn teammates
-
-Spawn all ${issues.length} teammates in parallel by sending a single message with ${issues.length} **Agent** tool calls. Each call must include \`team_name: "${teamName}"\` and a unique \`name\`. The team is created automatically when you spawn the first teammate with \`team_name\` — no separate setup step is needed.
-
-${teammateSpawns}
-
-### Step 2: Wait for ALL teammates to complete
-
-CRITICAL: After spawning, you MUST remain active and wait for every single teammate to finish. Each teammate automatically sends you an **idle notification** when they complete their work.
-
-Track completion against this checklist — ALL must report idle before you proceed:
-${issues.map(i => `- [ ] ${i.id.toLowerCase()}`).join('\n')}
-
-While waiting:
-- As each teammate goes idle, verify their output file exists on disk using the **Read** tool
-- If a teammate has not gone idle after 15 minutes, use **SendMessage** to check on them
-- Do NOT proceed to Step 3 until you have received idle notifications from ALL ${issues.length} teammates
-
-WARNING: The #1 failure mode is exiting before all teammates finish. If you exit early, all teammate processes are killed and their work is permanently lost. When in doubt, keep waiting. Err on the side of waiting too long rather than exiting too early.
-
-### Step 3: Verify outputs
-
-Once every teammate has gone idle:
-1. Verify each output file exists in ${outDir}/ using **Read** or **Glob**
-2. Verify each issue's front matter status is \`done\`
-3. If any teammate failed to write output or update status, do it yourself
-4. Do NOT modify STATE.md — the orchestrator handles that
-
-## Critical Rules
-
-- The team is created implicitly when you spawn the first teammate with \`team_name\`, and cleaned up automatically when all teammates exit. Your only job is to spawn teammates, wait, and verify.
-- You MUST wait for idle notifications from ALL ${issues.length} teammates before exiting. Exiting early kills all teammate processes and permanently loses their work.
-- Each teammate MUST write its output to disk — research only in conversation is LOST.
-- Each teammate MUST update the issue front matter status to \`done\`.
-- One issue per teammate — no cross-issue work.`;
-    }
-    /**
-     * Revert issues that stayed in_progress after a failed wave.
-     */
-    revertIncompleteIssues(issues) {
-        const pmDir = resolvePmDir(this.workingDir);
-        if (!pmDir)
-            return;
-        for (const issue of issues) {
-            const fullPath = join(pmDir, issue.path);
-            try {
-                const content = readFileSync(fullPath, 'utf-8');
-                if (content.match(/^status:\s*in_progress$/m)) {
-                    this.updateIssueFrontMatter(issue.path, issue.status);
-                }
-            }
-            catch { /* file may be gone */ }
+    /** Load issues from a specific board, auto-activating draft boards. Returns null on error. */
+    loadBoardIssues(pmDir, boardId) {
+        const boardState = parseBoardDirectory(pmDir, boardId);
+        if (!boardState) {
+            this.emit('error', `Board not found: ${boardId}`);
+            return null;
         }
-    }
-    // ── Teammate permissions ─────────────────────────────────────
-    /** Saved content of any pre-existing .claude/settings.json so we can restore it */
-    savedClaudeSettings = null;
-    claudeSettingsInstalled = false;
-    /**
-     * Pre-approve tools in project .claude/settings.json so Agent Teams
-     * teammates can work without interactive permission prompts.
-     * Teammates are separate processes that inherit the lead's permission
-     * settings. Without pre-approved tools, they hit interactive prompts
-     * that can't be answered in headless/background mode (known bug #25254).
-     */
-    installTeammatePermissions() {
-        const claudeDir = join(this.workingDir, '.claude');
-        const settingsPath = join(claudeDir, 'settings.json');
-        if (!existsSync(claudeDir)) {
-            mkdirSync(claudeDir, { recursive: true });
-        }
-        // Tools that teammates may need during execution
-        const requiredPermissions = [
-            'Bash',
-            'Read',
-            'Edit',
-            'Write',
-            'Glob',
-            'Grep',
-            'WebFetch',
-            'WebSearch',
-            'Agent',
-        ];
-        try {
-            // Save existing settings
-            if (existsSync(settingsPath)) {
-                this.savedClaudeSettings = readFileSync(settingsPath, 'utf-8');
-                const existing = JSON.parse(this.savedClaudeSettings);
-                // Merge permissions into existing settings
-                if (!existing.permissions)
-                    existing.permissions = {};
-                if (!existing.permissions.allow)
-                    existing.permissions.allow = [];
-                for (const tool of requiredPermissions) {
-                    if (!existing.permissions.allow.includes(tool)) {
-                        existing.permissions.allow.push(tool);
-                    }
-                }
-                writeFileSync(settingsPath, JSON.stringify(existing, null, 2));
-            }
-            else {
-                this.savedClaudeSettings = null;
-                writeFileSync(settingsPath, JSON.stringify({
-                    permissions: { allow: requiredPermissions },
-                }, null, 2));
-            }
-            this.claudeSettingsInstalled = true;
+        if (boardState.state.paused) {
+            this.emit('error', 'Board is paused');
+            return null;
         }
-        catch {
-            // Non-fatal — teammates may hit permission prompts
+        if (boardState.board.status === 'draft') {
+            this.activateBoard(pmDir, boardId);
         }
+        else if (boardState.board.status !== 'active') {
+            this.emit('error', `Board ${boardId} is not active (status: ${boardState.board.status})`);
+            return null;
+        }
+        return boardState.issues;
     }
-    /**
-     * Restore original .claude/settings.json after wave execution.
-     */
-    uninstallTeammatePermissions() {
-        if (!this.claudeSettingsInstalled)
-            return;
-        const settingsPath = join(this.workingDir, '.claude', 'settings.json');
-        try {
-            if (this.savedClaudeSettings !== null) {
-                writeFileSync(settingsPath, this.savedClaudeSettings);
-            }
-            else {
-                unlinkSync(settingsPath);
-            }
+    /** Load project-level issues (legacy or no boards). Returns null on error. */
+    loadProjectIssues() {
+        const fullState = parsePlanDirectory(this.workingDir);
+        if (!fullState) {
+            this.emit('error', 'No PM directory found');
+            return null;
         }
-        catch {
-            // Best effort
+        if (fullState.state.paused) {
+            this.emit('error', 'Project is paused');
+            return null;
         }
-        this.savedClaudeSettings = null;
-        this.claudeSettingsInstalled = false;
+        return fullState.issues;
     }
-    // ── Bouncer propagation for sub-agents ─────────────────────
-    /** Saved content of any pre-existing .mcp.json so we can restore it */
-    savedMcpJson = null;
-    mcpJsonInstalled = false;
-    /**
-     * Write .mcp.json in the working directory so Agent Teams teammates
-     * (separate processes) auto-discover the bouncer MCP server.
-     * This is essential — teammates don't inherit --mcp-config or
-     * --permission-prompt-tool from the team lead. .mcp.json project-level
-     * discovery + global PreToolUse hooks are the two bouncer paths for teammates.
-     *
-     * Also generates ~/.mstro/mcp-config.json for the team lead (--mcp-config).
-     */
-    installBouncerForSubagents() {
-        const mcpJsonPath = join(this.workingDir, '.mcp.json');
-        // Generate the standard MCP config (for parent --mcp-config) and reuse for sub-agents
+    /** Activate a draft board by updating its status in board.md. */
+    activateBoard(pmDir, boardId) {
+        const boardMdPath = join(pmDir, 'boards', boardId, 'board.md');
+        if (!existsSync(boardMdPath))
+            return;
         try {
-            const generatedPath = generateMcpConfig(this.workingDir);
-            if (!generatedPath)
-                return;
-            const mcpConfig = readFileSync(generatedPath, 'utf-8');
-            // Save any existing .mcp.json
-            if (existsSync(mcpJsonPath)) {
-                this.savedMcpJson = readFileSync(mcpJsonPath, 'utf-8');
-                // Merge: add bouncer to existing config
-                const existing = JSON.parse(this.savedMcpJson);
-                const generated = JSON.parse(mcpConfig);
-                existing.mcpServers = {
-                    ...existing.mcpServers,
-                    'mstro-bouncer': generated.mcpServers['mstro-bouncer'],
-                };
-                writeFileSync(mcpJsonPath, JSON.stringify(existing, null, 2));
-            }
-            else {
-                writeFileSync(mcpJsonPath, mcpConfig);
-            }
-            this.mcpJsonInstalled = true;
-        }
-        catch {
-            // Non-fatal: parent has MCP via --mcp-config, teammates fall back to PreToolUse hooks
+            const content = readFileSync(boardMdPath, 'utf-8');
+            writeFileSync(boardMdPath, replaceFrontMatterField(content, 'status', 'active'), 'utf-8');
         }
+        catch { /* non-fatal — pickReadyIssues will re-check */ }
     }
-    /**
-     * Restore or remove .mcp.json after execution.
-     */
-    uninstallBouncerForSubagents() {
-        if (!this.mcpJsonInstalled)
+    /** Check if all issues in a board are done and mark board as completed. */
+    tryCompleteBoardIfDone(pmDir, boardId, issues) {
+        const allDone = issues.length > 0 && issues.every(i => i.status === 'done' || i.status === 'cancelled');
+        if (!allDone)
+            return;
+        const boardMdPath = join(pmDir, 'boards', boardId, 'board.md');
+        if (!existsSync(boardMdPath))
             return;
-        const mcpJsonPath = join(this.workingDir, '.mcp.json');
         try {
-            if (this.savedMcpJson !== null) {
-                // Restore the original
-                writeFileSync(mcpJsonPath, this.savedMcpJson);
-            }
-            else {
-                // We created it — remove it
-                unlinkSync(mcpJsonPath);
-            }
+            let content = readFileSync(boardMdPath, 'utf-8');
+            content = replaceFrontMatterField(content, 'status', 'completed');
+            content = replaceFrontMatterField(content, 'completed_at', `"${new Date().toISOString()}"`);
+            writeFileSync(boardMdPath, content, 'utf-8');
         }
-        catch {
-            // Best effort cleanup
-        }
-        this.savedMcpJson = null;
-        this.mcpJsonInstalled = false;
-    }
-    // ── Helpers ───────────────────────────────────────────────────
-    /**
-     * Resolve the canonical output path for an issue in .pm/out/.
-     * This is the PM system's internal execution artifact — always under
-     * PM control. User-facing delivery to output_file happens via publishOutputs().
-     */
-    resolveOutputPath(issue) {
-        const pmDir = resolvePmDir(this.workingDir);
-        const outDir = pmDir ? join(pmDir, 'out') : join(this.workingDir, '.pm', 'out');
-        return join(outDir, `${issue.id}-${this.slugify(issue.title)}.md`);
+        catch { /* non-fatal */ }
     }
-    /**
-     * List existing execution output docs in .pm/out/.
-     * Single canonical location — no split-brain lookup.
-     */
-    listExistingDocs() {
+    resolveActiveBoardId() {
         const pmDir = resolvePmDir(this.workingDir);
         if (!pmDir)
-            return [];
-        const outDir = join(pmDir, 'out');
-        if (!existsSync(outDir))
-            return [];
+            return null;
         try {
-            return readdirSync(outDir)
-                .filter(f => f.endsWith('.md'))
-                .map(f => join(outDir, f));
+            const workspacePath = join(pmDir, 'workspace.json');
+            if (!existsSync(workspacePath))
+                return null;
+            const workspace = JSON.parse(readFileSync(workspacePath, 'utf-8'));
+            return workspace.activeBoardId ?? null;
         }
         catch {
-            return [];
+            return null;
         }
     }
-    /**
-     * 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.
-     * Failures are non-fatal — the canonical artifact in .pm/out/ is always safe.
-     */
-    publishOutputs(issues) {
+    revertIncompleteIssues(issues) {
         const pmDir = resolvePmDir(this.workingDir);
         if (!pmDir)
             return;
         for (const issue of issues) {
-            if (!issue.outputFile)
-                continue;
-            // Only publish for confirmed-done issues
-            try {
-                const content = readFileSync(join(pmDir, issue.path), 'utf-8');
-                if (!content.match(/^status:\s*done$/m))
-                    continue;
-            }
-            catch {
-                continue;
-            }
-            const srcPath = this.resolveOutputPath(issue);
-            if (!existsSync(srcPath))
-                continue;
-            // Guard against path traversal — output_file must resolve within workingDir
-            const destPath = resolve(this.workingDir, issue.outputFile);
-            if (!destPath.startsWith(this.workingDir + '/') && destPath !== this.workingDir) {
-                this.emit('output', {
-                    issueId: issue.id,
-                    text: `Warning: output_file "${issue.outputFile}" escapes project directory — skipping`,
-                });
-                continue;
-            }
+            const fullPath = join(pmDir, issue.path);
             try {
-                // Ensure destination directory exists
-                const destDir = join(destPath, '..');
-                if (!existsSync(destDir))
-                    mkdirSync(destDir, { recursive: true });
-                copyFileSync(srcPath, destPath);
-            }
-            catch {
-                // Non-fatal — canonical artifact is safe in .pm/out/
-                this.emit('output', {
-                    issueId: issue.id,
-                    text: `Warning: could not copy output to ${issue.outputFile}`,
-                });
+                const content = readFileSync(fullPath, 'utf-8');
+                if (content.match(/^status:\s*in_progress$/m)) {
+                    this.updateIssueFrontMatter(issue.path, issue.status);
+                }
             }
+            catch { /* file may be gone */ }
         }
     }
-    slugify(text) {
-        return text
-            .toLowerCase()
-            .replace(/[^a-z0-9]+/g, '-')
-            .replace(/^-+|-+$/g, '')
-            .slice(0, 60);
-    }
     updateIssueFrontMatter(issuePath, newStatus) {
         const pmDir = resolvePmDir(this.workingDir);
         if (!pmDir)
             return;
-        const fullPath = join(pmDir, issuePath);
         try {
-            let content = readFileSync(fullPath, 'utf-8');
-            content = content.replace(/^(status:\s*).+$/m, `$1${newStatus}`);
-            writeFileSync(fullPath, content, 'utf-8');
+            setFrontMatterField(join(pmDir, issuePath), 'status', newStatus);
         }
-        catch {
-            // Ignore errors — file may have been moved
+        catch { /* file may have been moved */ }
+    }
+    ensureOutputDirs() {
+        if (this.boardDir) {
+            const boardOutDir = join(this.boardDir, 'out');
+            if (!existsSync(boardOutDir))
+                mkdirSync(boardOutDir, { recursive: true });
+        }
+        else {
+            const pmDir = resolvePmDir(this.workingDir);
+            if (pmDir) {
+                const outDir = join(pmDir, 'out');
+                if (!existsSync(outDir))
+                    mkdirSync(outDir, { recursive: true });
+            }
         }
     }
-    /**
-     * Append a progress log entry after a wave completes.
-     * Re-reads issue files from disk to determine which actually completed.
-     */
     appendProgressEntry(issues, waveStart) {
         const pmDir = resolvePmDir(this.workingDir);
         if (!pmDir)
             return;
-        const progressPath = join(pmDir, 'progress.md');
-        if (!existsSync(progressPath))
-            return;
+        // Board-scoped progress log
+        const progressPath = this.boardDir
+            ? join(this.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);
-        // Re-read issue statuses from disk to get accurate completion count
         const completed = [];
         const failed = [];
         for (const issue of issues) {
@@ -629,13 +488,30 @@ Once every teammate has gone idle:
             lines.push(`- **Failed**: ${failed.join(', ')}`);
         }
         lines.push('');
+        this.writeProgressLines(progressPath, lines);
+    }
+    writeProgressLines(filePath, lines) {
         try {
-            const existing = readFileSync(progressPath, 'utf-8');
-            writeFileSync(progressPath, existing.trimEnd() + '\n' + lines.join('\n'), 'utf-8');
-        }
-        catch {
-            // Non-fatal
+            if (existsSync(filePath)) {
+                const existing = readFileSync(filePath, 'utf-8');
+                writeFileSync(filePath, `${existing.trimEnd()}\n${lines.join('\n')}`, 'utf-8');
+            }
+            else {
+                writeFileSync(filePath, `# Board Progress\n${lines.join('\n')}`, 'utf-8');
+            }
         }
+        catch { /* non-fatal */ }
+    }
+    /** Resolve the active board's directory path for outputs, reviews, and progress. */
+    resolveBoardDir() {
+        const pmDir = resolvePmDir(this.workingDir);
+        if (!pmDir)
+            return null;
+        const effectiveBoardId = this.boardId ?? this.resolveActiveBoardId();
+        if (!effectiveBoardId)
+            return null;
+        const boardDir = join(pmDir, 'boards', effectiveBoardId);
+        return existsSync(boardDir) ? boardDir : null;
     }
 }
 //# sourceMappingURL=executor.js.map