@telora/factory 0.4.5

package/dist/execution.js

@@ -0,0 +1,20 @@
+/**
+ * Factory execution -- barrel re-export.
+ *
+ * The implementation has been split into focused modules:
+ *   - builder-spawner.ts       -- builder process spawning, env setup, stream handling
+ *   - builder-completion.ts    -- builder completion handling, execution cycle orchestration
+ *   - execution-target.ts      -- BuilderExecutionTarget (TriggerExecutionTarget impl)
+ *   - work-unit-scheduler.ts   -- DAG-aware work unit readiness, dependency maps
+ *
+ * This file preserves the original import path for consumers (index.ts, tests).
+ */
+// Work unit scheduling
+export { findReadyWorkUnits } from './work-unit-scheduler.js';
+// Builder spawning
+export { spawnBuilder, transitionWorkUnitStatus, DEFAULT_MAX_ITERATIONS, LOG_PREFIX, lastGateOutputByWorkUnit } from './builder-spawner.js';
+// Builder completion & execution cycle
+export { handleBuilderCompletion, runExecutionCycle } from './builder-completion.js';
+// Execution target
+export { BuilderExecutionTarget, getBuilderTarget } from './execution-target.js';
+//# sourceMappingURL=execution.js.map

package/dist/execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.js","sourceRoot":"","sources":["../src/execution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,uBAAuB;AACvB,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAG9D,mBAAmB;AACnB,OAAO,EAAE,YAAY,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,UAAU,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAE5I,uCAAuC;AACvC,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAErF,mBAAmB;AACnB,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/factory-engine.d.ts

@@ -0,0 +1,100 @@
+/**
+ * FactoryEngine -- ExecutionEngine adapter for the factory orchestrator.
+ *
+ * Wraps the existing factory modules (config, instance-lifecycle, completion,
+ * crash-recovery, queries/shared) behind the ExecutionEngine interface so that
+ * the unified daemon process shell can manage the factory engine alongside
+ * other engines (strategy, etc.) through a single contract.
+ *
+ * Lifecycle sequence (driven by the process shell):
+ *   1. init(config)         -- validate config, init API client, validate auth
+ *   2. recoverFromCrash()   -- reconcile orphaned worktrees, stale sessions
+ *   3. start()              -- begin the 30s poll loop
+ *   ... running ...
+ *   4. stop()               -- stop accepting new work
+ *   5. shutdown()           -- kill builders, WIP commit worktrees, drain
+ */
+import type { ExecutionEngine, EngineHealth, ResourceUsage, BaseConfig } from '@telora/daemon-core';
+import type { ResourceGovernor } from '@telora/daemon-core';
+/**
+ * ExecutionEngine adapter for the Telora factory orchestrator.
+ *
+ * All engine-specific behavior is delegated to existing factory modules.
+ * This class is a thin wrapper that maps the ExecutionEngine lifecycle
+ * methods onto those modules.
+ */
+export declare class FactoryEngine implements ExecutionEngine {
+    readonly name = "factory";
+    /** Factory configuration, set during init(). */
+    private config;
+    /** Optional global resource governor for cross-engine concurrency control. */
+    private governor;
+    /** Periodic intervals to clear on stop(). */
+    private intervals;
+    /**
+     * Initialize the engine with its configuration.
+     *
+     * Validates config, initializes the API client, and verifies tracker
+     * authentication before any other engine method is called.
+     */
+    init(config: BaseConfig & Record<string, unknown>): Promise<void>;
+    /**
+     * Set the optional resource governor for global concurrency control.
+     *
+     * When set, all Claude Code process spawns within the factory acquire a
+     * slot from the governor before spawning and release it on exit. This
+     * provides cross-engine concurrency limiting in addition to the factory's
+     * own maxConcurrentInstances check.
+     */
+    setGovernor(gov: ResourceGovernor): void;
+    /**
+     * Recover from a previous crash.
+     *
+     * Delegates to the crash-recovery module which scans for orphaned
+     * worktrees, resets stale sessions, and pauses stuck instances.
+     */
+    recoverFromCrash(): Promise<void>;
+    /**
+     * Start the factory's polling loop.
+     *
+     * After this call the engine actively discovers and processes factory
+     * instances on a 30-second interval. Also runs startup log pruning and
+     * schedules periodic hourly pruning.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop accepting new work.
+     *
+     * Sets the shutdown flag (poll loop becomes a no-op), clears the
+     * poll interval, and stops periodic tasks. In-progress instances
+     * continue running.
+     */
+    stop(): void;
+    /**
+     * Graceful shutdown with full cleanup.
+     *
+     * 1. Kill active builder child processes (SIGTERM).
+     * 2. WIP commit uncommitted changes in instance worktrees.
+     * 3. Bail out if the 10-second timeout is exceeded.
+     *
+     * The engine is inert after this method returns.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Return a snapshot of the engine's health.
+     *
+     * Status is 'healthy' when there are active instances, 'degraded' when
+     * idle (no work items), and never 'unhealthy' under normal conditions
+     * (unhealthy would be set by an external monitor if the engine fails to
+     * respond).
+     */
+    healthCheck(): EngineHealth;
+    /**
+     * Return a snapshot of the engine's resource usage.
+     *
+     * - `activeClaudeProcesses`: total running builder sessions across all instances.
+     * - `activeWorktrees`: instances that have an allocated worktree path.
+     */
+    getResourceUsage(): ResourceUsage;
+}
+//# sourceMappingURL=factory-engine.d.ts.map

package/dist/factory-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory-engine.d.ts","sourceRoot":"","sources":["../src/factory-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACpG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AA2B5D;;;;;;GAMG;AACH,qBAAa,aAAc,YAAW,eAAe;IACnD,QAAQ,CAAC,IAAI,aAAa;IAE1B,gDAAgD;IAChD,OAAO,CAAC,MAAM,CAA8B;IAE5C,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAiC;IAEjD,6CAA6C;IAC7C,OAAO,CAAC,SAAS,CAAwC;IAMzD;;;;;OAKG;IACG,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAavE;;;;;;;OAOG;IACH,WAAW,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI;IASxC;;;;;OAKG;IACG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAWvC;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiC5B;;;;;;OAMG;IACH,IAAI,IAAI,IAAI;IAaZ;;;;;;;;OAQG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IA8C/B;;;;;;;OAOG;IACH,WAAW,IAAI,YAAY;IAqB3B;;;;;OAKG;IACH,gBAAgB,IAAI,aAAa;CAqBlC"}

package/dist/factory-engine.js

@@ -0,0 +1,243 @@
+/**
+ * FactoryEngine -- ExecutionEngine adapter for the factory orchestrator.
+ *
+ * Wraps the existing factory modules (config, instance-lifecycle, completion,
+ * crash-recovery, queries/shared) behind the ExecutionEngine interface so that
+ * the unified daemon process shell can manage the factory engine alongside
+ * other engines (strategy, etc.) through a single contract.
+ *
+ * Lifecycle sequence (driven by the process shell):
+ *   1. init(config)         -- validate config, init API client, validate auth
+ *   2. recoverFromCrash()   -- reconcile orphaned worktrees, stale sessions
+ *   3. start()              -- begin the 30s poll loop
+ *   ... running ...
+ *   4. stop()               -- stop accepting new work
+ *   5. shutdown()           -- kill builders, WIP commit worktrees, drain
+ */
+import { safeInterval } from '@telora/daemon-core';
+import { validateConfig } from './config.js';
+import { initApiClient, validateTrackerAuth } from './queries/shared.js';
+import { recoverFromCrash } from './crash-recovery.js';
+import { startPollLoop, stopPollLoop, getActiveInstances, setShuttingDown, setFactoryGovernor, } from './instance-lifecycle.js';
+import { commitWipOnShutdown } from './completion.js';
+import { pruneFactoryLogs, createFactoryLogManagerDeps } from './log-manager.js';
+// ---------------------------------------------------------------------------
+// Shutdown constants
+// ---------------------------------------------------------------------------
+/** Maximum time (ms) allowed for the graceful shutdown sequence. */
+const SHUTDOWN_TIMEOUT_MS = 10_000;
+// ---------------------------------------------------------------------------
+// FactoryEngine
+// ---------------------------------------------------------------------------
+/**
+ * ExecutionEngine adapter for the Telora factory orchestrator.
+ *
+ * All engine-specific behavior is delegated to existing factory modules.
+ * This class is a thin wrapper that maps the ExecutionEngine lifecycle
+ * methods onto those modules.
+ */
+export class FactoryEngine {
+    name = 'factory';
+    /** Factory configuration, set during init(). */
+    config = null;
+    /** Optional global resource governor for cross-engine concurrency control. */
+    governor = null;
+    /** Periodic intervals to clear on stop(). */
+    intervals = [];
+    // -------------------------------------------------------------------------
+    // Lifecycle: init
+    // -------------------------------------------------------------------------
+    /**
+     * Initialize the engine with its configuration.
+     *
+     * Validates config, initializes the API client, and verifies tracker
+     * authentication before any other engine method is called.
+     */
+    async init(config) {
+        const factoryConfig = config;
+        this.config = factoryConfig;
+        validateConfig(factoryConfig);
+        initApiClient(factoryConfig);
+        await validateTrackerAuth();
+    }
+    // -------------------------------------------------------------------------
+    // Resource governor
+    // -------------------------------------------------------------------------
+    /**
+     * Set the optional resource governor for global concurrency control.
+     *
+     * When set, all Claude Code process spawns within the factory acquire a
+     * slot from the governor before spawning and release it on exit. This
+     * provides cross-engine concurrency limiting in addition to the factory's
+     * own maxConcurrentInstances check.
+     */
+    setGovernor(gov) {
+        this.governor = gov;
+        setFactoryGovernor(gov);
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle: crash recovery
+    // -------------------------------------------------------------------------
+    /**
+     * Recover from a previous crash.
+     *
+     * Delegates to the crash-recovery module which scans for orphaned
+     * worktrees, resets stale sessions, and pauses stuck instances.
+     */
+    async recoverFromCrash() {
+        if (!this.config) {
+            throw new Error('FactoryEngine.recoverFromCrash() called before init()');
+        }
+        await recoverFromCrash(this.config);
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle: start
+    // -------------------------------------------------------------------------
+    /**
+     * Start the factory's polling loop.
+     *
+     * After this call the engine actively discovers and processes factory
+     * instances on a 30-second interval. Also runs startup log pruning and
+     * schedules periodic hourly pruning.
+     */
+    async start() {
+        if (!this.config) {
+            throw new Error('FactoryEngine.start() called before init()');
+        }
+        // Escalation-aware log preservation deps
+        const logDeps = createFactoryLogManagerDeps(this.config);
+        // Startup log pruning (non-fatal)
+        try {
+            await pruneFactoryLogs(this.config, logDeps);
+        }
+        catch (err) {
+            console.warn('[factory-engine] Startup log pruning failed (non-fatal):', err instanceof Error ? err.message : String(err));
+        }
+        startPollLoop(this.config);
+        // Periodic log pruning (hourly)
+        const config = this.config;
+        this.intervals.push(safeInterval(async () => {
+            await pruneFactoryLogs(config, logDeps);
+        }, 3_600_000, 'factory-log-prune'));
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle: stop
+    // -------------------------------------------------------------------------
+    /**
+     * Stop accepting new work.
+     *
+     * Sets the shutdown flag (poll loop becomes a no-op), clears the
+     * poll interval, and stops periodic tasks. In-progress instances
+     * continue running.
+     */
+    stop() {
+        for (const interval of this.intervals) {
+            clearInterval(interval);
+        }
+        this.intervals = [];
+        setShuttingDown();
+        stopPollLoop();
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle: shutdown
+    // -------------------------------------------------------------------------
+    /**
+     * Graceful shutdown with full cleanup.
+     *
+     * 1. Kill active builder child processes (SIGTERM).
+     * 2. WIP commit uncommitted changes in instance worktrees.
+     * 3. Bail out if the 10-second timeout is exceeded.
+     *
+     * The engine is inert after this method returns.
+     */
+    async shutdown() {
+        const shutdownStart = Date.now();
+        const instances = getActiveInstances();
+        for (const [instanceId, state] of instances) {
+            // Kill active builder child processes (legacy solo mode)
+            for (const [, builder] of state.activeBuilderSessions) {
+                try {
+                    process.kill(builder.pid, 'SIGTERM');
+                    console.log(`[factory-engine] Sent SIGTERM to builder pid ${builder.pid} ` +
+                        `(work unit ${builder.workUnitId})`);
+                }
+                catch {
+                    // Process may already be dead
+                }
+            }
+            // Terminate execution unit sessions (DAG-aware scheduler model)
+            const { terminateAllUnits } = await import('./unit-session-lifecycle.js');
+            terminateAllUnits(state);
+            // WIP commit any uncommitted changes in the worktree
+            if (state.worktreePath) {
+                try {
+                    await commitWipOnShutdown(instanceId, state.worktreePath, 'graceful-shutdown');
+                }
+                catch (err) {
+                    console.error(`[factory-engine] Failed to WIP commit for instance ${instanceId}: ` +
+                        `${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            // Bail out if we are taking too long
+            if (Date.now() - shutdownStart > SHUTDOWN_TIMEOUT_MS) {
+                console.warn('[factory-engine] Shutdown timeout reached, forcing exit');
+                break;
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Health check
+    // -------------------------------------------------------------------------
+    /**
+     * Return a snapshot of the engine's health.
+     *
+     * Status is 'healthy' when there are active instances, 'degraded' when
+     * idle (no work items), and never 'unhealthy' under normal conditions
+     * (unhealthy would be set by an external monitor if the engine fails to
+     * respond).
+     */
+    healthCheck() {
+        const instances = getActiveInstances();
+        const instanceDetails = {};
+        for (const [instanceId, state] of instances) {
+            instanceDetails[instanceId] = state.status;
+        }
+        return {
+            status: instances.size > 0 ? 'healthy' : 'degraded',
+            activeWorkItems: instances.size,
+            details: {
+                instances: instanceDetails,
+            },
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Resource usage
+    // -------------------------------------------------------------------------
+    /**
+     * Return a snapshot of the engine's resource usage.
+     *
+     * - `activeClaudeProcesses`: total running builder sessions across all instances.
+     * - `activeWorktrees`: instances that have an allocated worktree path.
+     */
+    getResourceUsage() {
+        const instances = getActiveInstances();
+        let activeClaudeProcesses = 0;
+        let activeWorktrees = 0;
+        for (const [, state] of instances) {
+            activeClaudeProcesses += state.activeBuilderSessions.size;
+            // Count execution unit sessions with active PIDs
+            for (const unit of state.executionUnits.values()) {
+                if (unit.pid !== null)
+                    activeClaudeProcesses++;
+            }
+            if (state.worktreePath) {
+                activeWorktrees++;
+            }
+        }
+        return {
+            activeClaudeProcesses,
+            activeWorktrees,
+        };
+    }
+}
+//# sourceMappingURL=factory-engine.js.map

package/dist/factory-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory-engine.js","sourceRoot":"","sources":["../src/factory-engine.ts"],"names":[],"mappings":"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"}

package/dist/gap-detection.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Gap analysis for factory re-planning.
+ *
+ * Detects gaps in completed work by analyzing gate results and completion
+ * evaluations. Provides:
+ *   - Verification gap filtering (strips test/build verification concerns)
+ *   - Prior cycle context formatting for re-planning prompts
+ *   - Strategy matching for assigning re-planned work units
+ */
+import type { FactoryCycleEvaluation, FactoryWorkUnit } from './types.js';
+import type { PersistedStrategy } from './strategy-design.js';
+/**
+ * Filter completion gate gaps to only include those describing absent
+ * functional capabilities. Strips verification-related gaps (test execution,
+ * build confirmation, etc.) that are not spec requirements.
+ */
+export declare function filterFunctionalGaps(gaps: Array<{
+    area: string;
+    description: string;
+    severity: string;
+}>): Array<{
+    area: string;
+    description: string;
+    severity: string;
+}>;
+/**
+ * Format prior cycle evaluations and completed work units into a concise
+ * markdown string for injection into the re-planning prompt.
+ *
+ * Rules:
+ * - Work unit descriptions truncated to ~100 chars to save context
+ * - Only completed work units included (not failed/pending)
+ * - Gap descriptions kept in full (they are the signal for what is missing)
+ * - Total output capped at MAX_PRIOR_CONTEXT_CHARS
+ */
+export declare function formatPriorCycleContext(evaluations: FactoryCycleEvaluation[], completedWorkUnits: FactoryWorkUnit[]): string;
+/**
+ * Best-effort matching of a new work unit to an existing strategy based on
+ * text similarity between the work unit title/description and strategy
+ * name/description. Returns the most relevant strategy ID or undefined.
+ */
+export declare function matchWorkUnitToStrategy(title: string, description: string, strategies: PersistedStrategy[]): string | undefined;
+//# sourceMappingURL=gap-detection.d.ts.map

package/dist/gap-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gap-detection.d.ts","sourceRoot":"","sources":["../src/gap-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,sBAAsB,EACtB,eAAe,EAChB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAyC9D;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,GACnE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAUhE;AAMD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,sBAAsB,EAAE,EACrC,kBAAkB,EAAE,eAAe,EAAE,GACpC,MAAM,CA6DR;AAMD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,iBAAiB,EAAE,GAC9B,MAAM,GAAG,SAAS,CAyBpB"}

package/dist/gap-detection.js

@@ -0,0 +1,149 @@
+/**
+ * Gap analysis for factory re-planning.
+ *
+ * Detects gaps in completed work by analyzing gate results and completion
+ * evaluations. Provides:
+ *   - Verification gap filtering (strips test/build verification concerns)
+ *   - Prior cycle context formatting for re-planning prompts
+ *   - Strategy matching for assigning re-planned work units
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/** Maximum character length for the prior cycle context to keep prompt budget. */
+const MAX_PRIOR_CONTEXT_CHARS = 4_000;
+/** Maximum character length for truncated work unit descriptions. */
+const MAX_WU_DESC_CHARS = 100;
+/** Log prefix for this module. */
+const LOG_PREFIX = '[replanning]';
+// ============================================================================
+// Gap filtering (strip verification-only gaps before re-planning)
+// ============================================================================
+/**
+ * Patterns that indicate a gap is about test execution, build verification,
+ * or command execution rather than a missing functional capability.
+ */
+const VERIFICATION_GAP_PATTERNS = [
+    /\bverif(y|ied|ication)\b.*\b(test|build|lint|typecheck|npm)\b/i,
+    /\b(run|execute|confirm)\b.*\b(test|build|lint|typecheck|npm)\b/i,
+    /\bnpm\s+(test|run\s+(build|lint|typecheck))\b/i,
+    /\btest\s+suite\s+(execution|run|pass)/i,
+    /\bbuild\s+(succeed|pass|valid)/i,
+    /\bensure\b.*\b(test|build|lint)\b.*\b(pass|succeed|run)/i,
+];
+/**
+ * Returns true if a gap describes a verification/test-execution concern
+ * rather than an absent functional capability.
+ */
+function isVerificationGap(gap) {
+    const text = `${gap.area} ${gap.description}`;
+    return VERIFICATION_GAP_PATTERNS.some((pattern) => pattern.test(text));
+}
+/**
+ * Filter completion gate gaps to only include those describing absent
+ * functional capabilities. Strips verification-related gaps (test execution,
+ * build confirmation, etc.) that are not spec requirements.
+ */
+export function filterFunctionalGaps(gaps) {
+    return gaps.filter((gap) => {
+        if (isVerificationGap(gap)) {
+            console.log(`${LOG_PREFIX} Filtered verification gap from re-planning context: ${gap.area}`);
+            return false;
+        }
+        return true;
+    });
+}
+// ============================================================================
+// Prior cycle context formatter (TEL-2)
+// ============================================================================
+/**
+ * Format prior cycle evaluations and completed work units into a concise
+ * markdown string for injection into the re-planning prompt.
+ *
+ * Rules:
+ * - Work unit descriptions truncated to ~100 chars to save context
+ * - Only completed work units included (not failed/pending)
+ * - Gap descriptions kept in full (they are the signal for what is missing)
+ * - Total output capped at MAX_PRIOR_CONTEXT_CHARS
+ */
+export function formatPriorCycleContext(evaluations, completedWorkUnits) {
+    if (evaluations.length === 0) {
+        return '';
+    }
+    const parts = ['## Prior Cycle History', ''];
+    for (const evaluation of evaluations) {
+        parts.push(`### Cycle ${evaluation.cycleNumber}`);
+        parts.push(`Evaluation: ${evaluation.passed ? 'PASSED' : 'FAILED'} ` +
+            `(confidence: ${evaluation.confidence})`);
+        parts.push(`Summary: ${evaluation.summary}`);
+        // Filter to functional gaps only (strip verification/test-execution gaps)
+        const functionalGaps = filterFunctionalGaps(evaluation.gaps);
+        // Critical gaps
+        const criticalGaps = functionalGaps.filter((g) => g.severity === 'critical');
+        if (criticalGaps.length > 0) {
+            parts.push('Critical gaps found:');
+            for (const gap of criticalGaps) {
+                parts.push(`- ${gap.area}: ${gap.description}`);
+            }
+        }
+        // Important gaps (brief)
+        const importantGaps = functionalGaps.filter((g) => g.severity === 'important');
+        if (importantGaps.length > 0) {
+            parts.push(`Important gaps (${importantGaps.length}): ${importantGaps.map((g) => g.area).join(', ')}`);
+        }
+        // Work units completed in this cycle
+        const cycleUnits = completedWorkUnits.filter((wu) => wu.cycleNumber === evaluation.cycleNumber);
+        if (cycleUnits.length > 0) {
+            parts.push(`Work completed (${cycleUnits.length} units):`);
+            for (const wu of cycleUnits) {
+                const desc = wu.description
+                    ? wu.description.length > MAX_WU_DESC_CHARS
+                        ? wu.description.slice(0, MAX_WU_DESC_CHARS) + '...'
+                        : wu.description
+                    : 'No description';
+                parts.push(`- ${wu.title}: ${desc}`);
+            }
+        }
+        parts.push('');
+    }
+    let formatted = parts.join('\n');
+    // Truncate if over budget
+    if (formatted.length > MAX_PRIOR_CONTEXT_CHARS) {
+        const truncationNote = '\n\n[Prior cycle context truncated due to size constraints]';
+        formatted = formatted.slice(0, MAX_PRIOR_CONTEXT_CHARS - truncationNote.length) + truncationNote;
+    }
+    return formatted;
+}
+// ============================================================================
+// Strategy matching for re-planned work units
+// ============================================================================
+/**
+ * Best-effort matching of a new work unit to an existing strategy based on
+ * text similarity between the work unit title/description and strategy
+ * name/description. Returns the most relevant strategy ID or undefined.
+ */
+export function matchWorkUnitToStrategy(title, description, strategies) {
+    if (strategies.length === 0)
+        return undefined;
+    const text = `${title} ${description}`.toLowerCase();
+    let bestScore = 0;
+    let bestId;
+    for (const strategy of strategies) {
+        const keywords = [
+            strategy.name.toLowerCase(),
+            ...(strategy.description?.toLowerCase().split(/\s+/) ?? []),
+        ];
+        let score = 0;
+        for (const kw of keywords) {
+            if (kw.length >= 3 && text.includes(kw)) {
+                score += kw.length;
+            }
+        }
+        if (score > bestScore) {
+            bestScore = score;
+            bestId = strategy.id;
+        }
+    }
+    return bestId;
+}
+//# sourceMappingURL=gap-detection.js.map

package/dist/gap-detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gap-detection.js","sourceRoot":"","sources":["../src/gap-detection.ts"],"names":[],"mappings":"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"}

package/dist/gate-context.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Gate context formatter.
+ *
+ * Builds a human-readable summary of which gate layers were enabled on a
+ * blueprint and what they validate. Used to give AI reviewers and planners
+ * context about which validation dimensions the gate system already handles,
+ * so they do not flag test coverage, type safety, or E2E behavior as gaps.
+ *
+ * This module has no dependencies other than types, so it can be safely
+ * imported by any prompt builder without pulling in the full gate stack.
+ */
+import type { FactoryBlueprint } from './types.js';
+/**
+ * Build a human-readable summary of which gates were enabled on this blueprint
+ * and what they validated.
+ *
+ * Called only when all strategy-level gates have already passed, so every
+ * gate listed here is known to have succeeded before the review runs.
+ *
+ * Returns an empty string if no gates are enabled (caller should skip the section).
+ */
+export declare function formatGateContext(blueprint: FactoryBlueprint): string;
+//# sourceMappingURL=gate-context.d.ts.map

package/dist/gate-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-context.d.ts","sourceRoot":"","sources":["../src/gate-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,gBAAgB,GAAG,MAAM,CA+CrE"}