@lumenflow/initiatives 1.0.0

package/dist/initiative-orchestrator.d.ts

@@ -0,0 +1,341 @@
+/**
+ * Initiative Orchestrator (WU-1581, WU-1821)
+ *
+ * Core orchestration logic for parallel agent execution of initiative WUs.
+ * Builds execution plans based on WU dependencies and manages wave-based execution.
+ *
+ * Architecture:
+ * - Loads initiative(s) and their WUs
+ * - Builds dependency graph for topological ordering
+ * - Groups independent WUs into parallel execution waves
+ * - Generates spawn commands for agent delegation
+ *
+ * WU-1821 additions:
+ * - Checkpoint-per-wave pattern for context management
+ * - Wave manifest files for idempotent resumption
+ * - Compact output for token discipline
+ *
+ * @see {@link tools/orchestrate-initiative.mjs} - CLI entry point
+ * @see {@link tools/lib/initiative-yaml.mjs} - Initiative loading
+ * @see {@link tools/lib/dependency-graph.mjs} - Dependency graph utilities
+ */
+import type { InitiativeDoc, WUEntry } from './initiative-yaml.js';
+/**
+ * Options for checkpoint mode resolution.
+ */
+export interface CheckpointOptions {
+    checkpointPerWave?: boolean;
+    noCheckpoint?: boolean;
+    dryRun?: boolean;
+}
+/**
+ * Result of checkpoint mode resolution.
+ */
+export interface CheckpointModeResult {
+    enabled: boolean;
+    source: 'explicit' | 'override' | 'auto' | 'dryrun';
+    reason?: string;
+}
+/**
+ * Result of auto-detection for checkpoint mode.
+ */
+export interface AutoCheckpointResult {
+    autoEnabled: boolean;
+    reason: string;
+    pendingCount: number;
+    waveCount: number;
+}
+/**
+ * Skipped WU entry with reason.
+ */
+export interface SkippedWUEntry {
+    id: string;
+    reason: string;
+}
+/**
+ * Deferred WU entry with blockers.
+ */
+export interface DeferredWUEntry {
+    id: string;
+    blockedBy: string[];
+    reason: string;
+}
+/**
+ * Execution plan result.
+ */
+export interface ExecutionPlan {
+    waves: WUEntry[][];
+    skipped: string[];
+    skippedWithReasons: SkippedWUEntry[];
+    deferred: DeferredWUEntry[];
+}
+/**
+ * Progress statistics for WUs.
+ */
+export interface ProgressStats {
+    total: number;
+    done: number;
+    active: number;
+    pending: number;
+    blocked: number;
+    percentage: number;
+}
+/**
+ * Bottleneck WU entry.
+ */
+export interface BottleneckWU {
+    id: string;
+    title: string;
+    blocksCount: number;
+}
+/**
+ * Wave manifest WU entry.
+ */
+export interface WaveManifestWU {
+    id: string;
+    lane?: string;
+    status?: string;
+}
+/**
+ * Wave manifest structure.
+ */
+export interface WaveManifest {
+    initiative: string;
+    wave: number;
+    created_at?: string;
+    wus: WaveManifestWU[];
+    lane_validation?: string;
+    done_criteria?: string;
+}
+/**
+ * Checkpoint wave result.
+ */
+export interface CheckpointWaveResult {
+    initiative: string;
+    wave: number;
+    wus: WaveManifestWU[];
+    manifestPath: string | null;
+    blockedBy?: string[];
+    waitingMessage?: string;
+    dryRun?: boolean;
+}
+/**
+ * Dependency filter result.
+ */
+export interface DependencyFilterResult {
+    spawnable: WUEntry[];
+    blocked: WUEntry[];
+    blockingDeps: string[];
+    waitingMessage: string;
+}
+/**
+ * Log prefix for orchestrator messages.
+ */
+declare const LOG_PREFIX = "[orchestrate:initiative]";
+/**
+ * WU-1828: Auto-detection thresholds for checkpoint mode.
+ *
+ * These thresholds determine when checkpoint mode is automatically enabled
+ * to prevent "prompt too long" errors for large initiatives.
+ *
+ * @type {{WU_COUNT: number, WAVE_COUNT: number}}
+ */
+export declare const CHECKPOINT_AUTO_THRESHOLDS: {
+    /** Auto-enable checkpoint mode if pending WU count exceeds this (>3 = 4+) */
+    WU_COUNT: number;
+    /** Auto-enable checkpoint mode if wave count exceeds this (>2 = 3+) */
+    WAVE_COUNT: number;
+};
+/**
+ * Load initiative and its WUs.
+ *
+ * @param {string} initRef - Initiative ID or slug
+ * @returns {{initiative: object, wus: Array<{id: string, doc: object}>}}
+ * @throws {Error} If initiative not found
+ */
+export declare function loadInitiativeWUs(initRef: string): {
+    initiative: InitiativeDoc;
+    wus: WUEntry[];
+};
+/**
+ * Load multiple initiatives and combine their WUs.
+ *
+ * Used for cross-initiative parallel execution.
+ *
+ * @param {string[]} initRefs - Array of initiative IDs or slugs
+ * @returns {Array<{id: string, doc: object}>} Combined WUs from all initiatives
+ * @throws {Error} If any initiative not found
+ */
+export declare function loadMultipleInitiatives(initRefs: string[]): WUEntry[];
+/**
+ * Build execution plan from WUs.
+ *
+ * Groups WUs into waves based on dependencies:
+ * - Wave 0: All WUs with no blockers (can run in parallel)
+ * - Wave 1: WUs blocked by wave 0 WUs only
+ * - Wave N: WUs blocked by wave N-1 WUs
+ *
+ * WU-2430: Enhanced filtering:
+ * - Only schedules status: ready WUs (not blocked/in_progress)
+ * - Reports skipped WUs with reasons (skippedWithReasons)
+ * - Defers WUs with unstamped external dependencies (deferred)
+ *
+ * @param {Array<{id: string, doc: object}>} wus - WUs to plan
+ * @returns {{waves: Array<Array<{id: string, doc: object}>>, skipped: string[], skippedWithReasons: Array<{id: string, reason: string}>, deferred: Array<{id: string, blockedBy: string[], reason: string}>}}
+ * @throws {Error} If circular dependencies detected
+ */
+export declare function buildExecutionPlan(wus: WUEntry[]): ExecutionPlan;
+/**
+ * WU-1828: Determine if checkpoint mode should be auto-enabled based on initiative size.
+ *
+ * Auto-detection triggers checkpoint mode when:
+ * - Pending WU count exceeds WU_COUNT threshold (>3)
+ * - OR wave count exceeds WAVE_COUNT threshold (>2)
+ *
+ * This prevents "prompt too long" errors for large initiatives by using
+ * checkpoint-per-wave execution instead of polling mode.
+ *
+ * @param {Array<{id: string, doc: object}>} wus - WUs to analyse
+ * @returns {{autoEnabled: boolean, reason: string, pendingCount: number, waveCount: number}}
+ */
+export declare function shouldAutoEnableCheckpoint(wus: WUEntry[]): AutoCheckpointResult;
+/**
+ * WU-1828: Resolve checkpoint mode from CLI flags and auto-detection.
+ * WU-2430: Updated to suppress auto-detection in dry-run mode.
+ *
+ * Flag precedence:
+ * 1. --checkpoint-per-wave (-c): Explicitly enables checkpoint mode
+ * 2. --no-checkpoint: Explicitly disables checkpoint mode (overrides auto-detection)
+ * 3. --dry-run: Suppresses auto-detection (dry-run uses polling mode for preview)
+ * 4. Auto-detection: Enabled based on initiative size if no explicit flags
+ *
+ * @param {{checkpointPerWave?: boolean, noCheckpoint?: boolean, dryRun?: boolean}} options - CLI options
+ * @param {Array<{id: string, doc: object}>} wus - WUs for auto-detection
+ * @returns {{enabled: boolean, source: 'explicit'|'override'|'auto'|'dryrun', reason?: string}}
+ */
+export declare function resolveCheckpointMode(options: CheckpointOptions, wus: WUEntry[]): CheckpointModeResult;
+/**
+ * Get bottleneck WUs from a set of WUs based on how many downstream WUs they block.
+ * A bottleneck is a WU that blocks multiple other WUs.
+ *
+ * @param {Array<{id: string, doc: object}>} wus - WUs to analyse
+ * @param {number} [limit=5] - Maximum number of bottlenecks to return
+ * @returns {Array<{id: string, title: string, blocksCount: number}>} Bottleneck WUs sorted by impact
+ */
+export declare function getBottleneckWUs(wus: WUEntry[], limit?: number): BottleneckWU[];
+/**
+ * Format execution plan for display.
+ *
+ * WU-2430: Enhanced to show skippedWithReasons and deferred WUs.
+ *
+ * @param {object} initiative - Initiative document
+ * @param {{waves: Array<Array<{id: string, doc: object}>>, skipped: string[], skippedWithReasons?: Array<{id: string, reason: string}>, deferred?: Array<{id: string, blockedBy: string[], reason: string}>}} plan - Execution plan
+ * @returns {string} Formatted plan output
+ */
+export declare function formatExecutionPlan(initiative: InitiativeDoc, plan: ExecutionPlan): string;
+/**
+ * Generate spawn commands for a wave of WUs.
+ *
+ * @param {Array<{id: string, doc: object}>} wave - WUs in the wave
+ * @returns {string[]} Array of spawn command strings
+ */
+export declare function generateSpawnCommands(wave: WUEntry[]): string[];
+/**
+ * Calculate progress statistics for WUs.
+ *
+ * @param {Array<{id: string, doc: object}>} wus - WUs to calculate progress for
+ * @returns {{total: number, done: number, active: number, pending: number, blocked: number, percentage: number}}
+ */
+export declare function calculateProgress(wus: WUEntry[]): ProgressStats;
+/**
+ * Format progress for display.
+ *
+ * @param {{total: number, done: number, active: number, pending: number, blocked: number, percentage: number}} progress
+ * @returns {string} Formatted progress string
+ */
+export declare function formatProgress(progress: ProgressStats): string;
+/**
+ * WU-2040: Filter WUs by dependency stamp status.
+ *
+ * A WU is only spawnable if ALL its blocked_by dependencies have stamps.
+ * This implements the wait-for-completion pattern per Anthropic multi-agent research.
+ *
+ * @param {Array<{id: string, doc: {blocked_by?: string[], lane: string, status: string}}>} candidates - WU candidates
+ * @returns {{spawnable: Array<object>, blocked: Array<object>, blockingDeps: string[], waitingMessage: string}}
+ */
+export declare function filterByDependencyStamps(candidates: WUEntry[]): DependencyFilterResult;
+/**
+ * Validate checkpoint-per-wave flag combinations.
+ *
+ * WU-1828: Extended to validate --no-checkpoint flag combinations.
+ *
+ * @param {{checkpointPerWave?: boolean, dryRun?: boolean, noCheckpoint?: boolean}} options - CLI options
+ * @throws {Error} If invalid flag combination
+ */
+export declare function validateCheckpointFlags(options: CheckpointOptions): void;
+/**
+ * Build a checkpoint wave for an initiative.
+ *
+ * WU-1821: Creates a wave manifest file and returns spawn candidates.
+ * Implements idempotency: skips WUs with stamps or already in previous manifests.
+ *
+ * Idempotency precedence (single source of truth):
+ * 1. Stamp (highest): .beacon/stamps/WU-XXXX.done exists → WU is done
+ * 2. Manifest: WU already in previous wave manifest → skip
+ * 3. Status: Only spawn status: ready WUs
+ *
+ * @param {string} initRef - Initiative ID or slug
+ * @returns {{wave: number, wus: Array<{id: string, lane: string, status: string}>, manifestPath: string, initiative: string}|null}
+ *   Wave data or null if all WUs complete
+ */
+export declare function buildCheckpointWave(initRef: string, options?: CheckpointOptions): CheckpointWaveResult | null;
+/**
+ * Format checkpoint wave output with Task invocations.
+ *
+ * WU-1821: Token discipline - keep output minimal for context management.
+ * WU-2040: Output full Task invocation blocks instead of pnpm wu:spawn meta-prompts.
+ * WU-2280: Prevent false wave spawned confusion - use markdown code blocks and ACTION REQUIRED banner.
+ * WU-2430: Handle dry-run mode - indicate preview mode clearly.
+ *
+ * @param {{initiative: string, wave: number, wus: Array<{id: string, lane: string}>, manifestPath: string, blockedBy?: string[], waitingMessage?: string, dryRun?: boolean}} waveData
+ * @returns {string} Formatted output with embedded Task invocations
+ */
+export declare function formatCheckpointOutput(waveData: CheckpointWaveResult): string;
+/**
+ * WU-2027: Generate embedded spawn prompt for a WU.
+ *
+ * Instead of outputting a meta-prompt like "Run: pnpm wu:spawn --id WU-XXX",
+ * this function runs the spawn logic internally and returns the full ~3KB
+ * prompt content ready for embedding in a Task invocation.
+ *
+ * This follows Anthropic guidance that sub-agent prompts must be fully
+ * self-contained to prevent delegation failures.
+ *
+ * @param {string} wuId - WU ID (e.g., 'WU-001')
+ * @returns {string} Escaped spawn prompt content ready for XML embedding
+ * @throws {Error} If WU file not found or cannot be parsed
+ */
+export declare function generateEmbeddedSpawnPrompt(wuId: string): string;
+/**
+ * WU-2027: Format a Task invocation with embedded spawn content for a WU.
+ *
+ * Creates a complete Task tool invocation block with the full spawn prompt
+ * embedded directly, rather than a meta-prompt referencing wu:spawn.
+ *
+ * @param {{id: string, doc: object}} wu - WU with id and YAML doc
+ * @returns {string} Complete Task invocation with embedded spawn content
+ */
+export declare function formatTaskInvocationWithEmbeddedSpawn(wu: WUEntry): string;
+/**
+ * WU-2027: Format execution plan with embedded spawns (no meta-prompts).
+ * WU-2280: Updated to use markdown code blocks and ACTION REQUIRED banner.
+ *
+ * Generates Task invocation blocks for all WUs in the execution plan,
+ * with full spawn content embedded directly. This replaces the meta-prompt
+ * pattern that was causing delegation failures.
+ *
+ * @param {{waves: Array<Array<{id: string, doc: object}>>, skipped: string[]}} plan - Execution plan
+ * @returns {string} Formatted output with embedded Task invocations
+ */
+export declare function formatExecutionPlanWithEmbeddedSpawns(plan: ExecutionPlan): string;
+export { LOG_PREFIX };