@lumenflow/core 3.1.3 → 3.2.1

package/dist/core/worktree-guard.js

@@ -0,0 +1,245 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * @file worktree-guard.ts
+ * @description WU context validation and main branch protection (WU-1396)
+ *
+ * Provides runtime guards to enforce worktree discipline:
+ * - Detect if current directory is inside a worktree
+ * - Extract WU ID and lane from worktree path or git branch
+ * - Throw descriptive error when write operations attempted outside worktree
+ * - Check if on main/master branch
+ *
+ * Used by wu- scripts to prevent writes to main checkout when worktrees exist.
+ * Complements .claude/hooks/user-prompt-submit-hook (human agent protection).
+ *
+ * @see {@link .claude/hooks/user-prompt-submit-hook} - Agent blocking hook
+ * @see {@link docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md} - Worktree discipline
+ */
+import path from 'node:path';
+import { createGitForPath } from '../git-adapter.js';
+import { BRANCHES } from '../wu-constants.js';
+/**
+ * Worktree path pattern: worktrees/<lane-kebab>-wu-<id>
+ * Captures: lane (kebab-case) and WU ID number
+ *
+ * Examples:
+ * - worktrees/operations-tooling-wu-1396
+ * - worktrees/intelligence-wu-789
+ * - worktrees/core-systems-api-wu-456
+ */
+const WORKTREE_PATH_PATTERN = /worktrees\/([\w-]+)-wu-(\d+)/;
+/**
+ * Lane branch pattern: lane/<lane-kebab>/wu-<id>
+ * Captures: lane (kebab-case) and WU ID number
+ *
+ * Examples:
+ * - lane/operations-tooling/wu-1396
+ * - lane/intelligence/wu-789
+ * - lane/core-systems-api/wu-456
+ */
+const LANE_BRANCH_PATTERN = /^lane\/([\w-]+)\/wu-(\d+)$/;
+/**
+ * Check if on main or master branch
+ *
+ * @param {GitOptions} [options] - Options
+ * @returns {Promise<boolean>} True if on main/master branch
+ *
+ * @example
+ * if (await isMainBranch()) {
+ *   console.log('On main branch');
+ * }
+ */
+export async function isMainBranch(options = {}) {
+    const git = options.git || createGitForPath(process.cwd());
+    const branch = await git.getCurrentBranch();
+    return branch === BRANCHES.MAIN || branch === BRANCHES.MASTER;
+}
+/**
+ * Normalize path separators to forward slashes
+ *
+ * Handles both Unix and Windows path separators for cross-platform compatibility.
+ *
+ * @param {string} p - Path to normalize
+ * @returns {string} Path with forward slashes
+ * @private
+ */
+function normalizePath(p) {
+    // Replace both backslashes and path.sep with forward slashes
+    // This handles Windows paths on Linux during testing
+    return p.replace(/\\/g, '/').split(path.sep).join('/');
+}
+/**
+ * Check if current directory is inside a worktree
+ *
+ * Detects worktree by checking if path contains worktrees/<lane>-wu-<id> pattern.
+ * Works correctly from nested directories within worktree.
+ *
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Current working directory (defaults to process.cwd())
+ * @returns {boolean} True if inside a worktree directory
+ *
+ * @example
+ * if (isInWorktree()) {
+ *   console.log('Working in a worktree');
+ * }
+ *
+ * // From nested directory
+ * isInWorktree({ cwd: '/project/worktrees/operations-wu-123/tools/lib' }); // true
+ */
+export function isInWorktree(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    // Normalize path separators for cross-platform compatibility
+    const normalizedPath = normalizePath(cwd);
+    return WORKTREE_PATH_PATTERN.test(normalizedPath);
+}
+/**
+ * Extract WU context from worktree path
+ *
+ * @param {string} cwd - Current working directory
+ * @returns {Object|null} Context object or null if not a worktree path
+ * @private
+ */
+function extractFromWorktreePath(cwd) {
+    const normalizedPath = normalizePath(cwd);
+    const match = normalizedPath.match(WORKTREE_PATH_PATTERN);
+    if (!match) {
+        return null;
+    }
+    const [fullMatch, lane, wuIdNumber] = match;
+    const wuId = `WU-${wuIdNumber}`;
+    // Extract just the worktrees/<lane>-wu-<id> part (not full absolute path)
+    const worktreePathMatch = fullMatch.match(/(worktrees\/[\w-]+-wu-\d+)/);
+    const worktreePath = worktreePathMatch ? worktreePathMatch[1] : null;
+    return {
+        wuId,
+        lane,
+        worktreePath,
+    };
+}
+/**
+ * Extract WU context from git branch name
+ *
+ * @param {Object} git - GitAdapter instance
+ * @returns {Promise<Object|null>} Context object or null if not a lane branch
+ * @private
+ */
+async function extractFromBranch(git) {
+    const branch = await git.getCurrentBranch();
+    const match = branch.match(LANE_BRANCH_PATTERN);
+    if (!match) {
+        return null;
+    }
+    const [, lane, wuIdNumber] = match;
+    const wuId = `WU-${wuIdNumber}`;
+    return {
+        wuId,
+        lane,
+        worktreePath: null, // Not in worktree, on lane branch
+    };
+}
+/**
+ * Get WU context from current directory or git branch
+ *
+ * Extracts WU ID, lane, and worktree path from:
+ * 1. Worktree directory path (priority) - works from nested directories
+ * 2. Git branch name (fallback) - lane/operations-tooling/wu-1396
+ *
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Current working directory (defaults to process.cwd())
+ * @param {Object} [options.git] - GitAdapter instance (for testing)
+ * @returns {Promise<Object|null>} WU context or null if not in WU workspace
+ *
+ * @example
+ * // From worktree
+ * const ctx = await getWUContext();
+ * // { wuId: 'WU-1396', lane: 'operations-tooling', worktreePath: 'worktrees/operations-tooling-wu-1396' }
+ *
+ * // From lane branch (not in worktree)
+ * const ctx = await getWUContext();
+ * // { wuId: 'WU-1396', lane: 'operations-tooling', worktreePath: null }
+ *
+ * // From main checkout on main branch
+ * const ctx = await getWUContext();
+ * // null
+ */
+export async function getWUContext(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    // Fast path: Try worktree path first (no git operations needed)
+    const worktreeContext = extractFromWorktreePath(cwd);
+    if (worktreeContext) {
+        return worktreeContext;
+    }
+    // Fallback to git branch detection (requires git operations)
+    // Only create git adapter if we have one provided or if we need to check branch
+    if (options.git) {
+        return await extractFromBranch(options.git);
+    }
+    // Create git adapter only if needed (path wasn't a worktree)
+    const git = createGitForPath(cwd);
+    return await extractFromBranch(git);
+}
+/**
+ * Assert that current context is inside a worktree or on a lane branch
+ *
+ * Throws descriptive error if:
+ * - On main/master branch AND
+ * - Not in a worktree directory
+ *
+ * Used by write operations to prevent modifications to main checkout.
+ *
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Current working directory (defaults to process.cwd())
+ * @param {Object} [options.git] - GitAdapter instance (for testing)
+ * @param {string} [options.operation] - Operation name for error message
+ * @throws {Error} If not in worktree and on main branch
+ *
+ * @example
+ * // In a wu- script write operation
+ * await assertWorktreeRequired({ operation: 'wu:claim' });
+ *
+ * // Will throw if on main in main checkout:
+ * // Error: BLOCKED: Operation 'wu:claim' requires a worktree.
+ * //        You are on 'main' branch in main checkout.
+ * //        ...
+ */
+export async function assertWorktreeRequired(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const operation = options.operation || 'this operation';
+    // Fast path: Check worktree path first (no git operations needed)
+    const worktreeContext = extractFromWorktreePath(cwd);
+    if (worktreeContext) {
+        return; // In worktree, allow operation
+    }
+    // Need git operations to check branch
+    const git = options.git || createGitForPath(cwd);
+    // Check if on lane branch
+    const branchContext = await extractFromBranch(git);
+    if (branchContext) {
+        return; // On lane branch, allow operation
+    }
+    // Check if on main branch
+    const onMain = await isMainBranch({ git });
+    if (onMain) {
+        throw new Error(`❌ BLOCKED: Operation '${operation}' requires a worktree.
+
+You are on 'main' branch in main checkout.
+
+To fix:
+  1. Claim a WU first:
+     pnpm wu:claim --id WU-1234 --lane "Operations: Tooling"
+
+  2. Navigate to the worktree:
+     cd worktrees/operations-tooling-wu-1234/
+
+  3. Run your operation from the worktree.
+
+For more information:
+  See CLAUDE.md §2 (Worktree Discipline)
+  See .claude/skills/worktree-discipline/SKILL.md
+`);
+    }
+    // Pass if on a non-main branch (e.g., feature branch) - allow for flexibility
+    // This case is less strict since it's not the main branch
+}
+//# sourceMappingURL=worktree-guard.js.map

package/dist/core/worktree-guard.js.map

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

package/dist/coverage-gate.d.ts

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * Coverage Gate for Quality Gates
+ *
+ * WU-1433: Adds coverage checking to gates with configurable mode (warn/block).
+ * Enforces ≥90% coverage on hex core files (application layer).
+ *
+ * Mode flag allows gradual rollout:
+ * - warn: Log failures but don't block (default)
+ * - block: Fail the gate if thresholds not met
+ *
+ * @see {@link packages/@lumenflow/cli/src/gates.ts} - Integration point
+ * @see {@link vitest.config.ts} - Coverage thresholds
+ */
+/**
+ * Coverage gate modes
+ * @constant
+ */
+export declare const COVERAGE_GATE_MODES: Readonly<{
+    /** Log warnings but don't fail the gate */
+    WARN: "warn";
+    /** Fail the gate if thresholds not met */
+    BLOCK: "block";
+}>;
+/**
+ * Glob patterns for hex core files that require ≥90% coverage.
+ * These are the critical application layer files.
+ *
+ * WU-1068: Changed from @exampleapp to @lumenflow for framework reusability.
+ * Project-specific patterns should be configured in workspace.yaml.
+ *
+ * @constant {string[]}
+ */
+export declare const HEX_CORE_PATTERNS: readonly string[];
+/**
+ * Default coverage threshold for hex core files (percentage)
+ * WU-1262: Kept for backwards compatibility.
+ * WU-2044: Now delegates to DEFAULT_MIN_COVERAGE from gate-constants.ts (DRY).
+ * The actual threshold is determined by resolveCoverageConfig() based on methodology.
+ * @constant {number}
+ */
+export declare const COVERAGE_THRESHOLD = 90;
+/**
+ * Default path to coverage summary JSON
+ * @constant {string}
+ */
+export declare const DEFAULT_COVERAGE_PATH = "coverage/coverage-summary.json";
+/**
+ * Check if a file path is in the hex core layer.
+ *
+ * WU-2448: Coverage reporters may emit absolute paths (e.g., <repo-root>/packages/...)
+ * or file:// URLs; use substring matching so hex-core checks still apply.
+ *
+ * @param {string|null|undefined} filePath - File path to check
+ * @returns {boolean} True if file is in hex core layer
+ */
+export declare function isHexCoreFile(filePath: UnsafeAny): boolean;
+/**
+ * Parse coverage JSON file.
+ *
+ * @param {string} coveragePath - Path to coverage-summary.json
+ * @returns {object|null} Parsed coverage data or null if invalid
+ */
+export declare function parseCoverageJson(coveragePath: UnsafeAny): {
+    total: any;
+    files: Record<string, unknown>;
+} | null;
+/**
+ * Check if coverage meets thresholds for hex core files.
+ *
+ * @param {object|null} coverageData - Parsed coverage data
+ * @param {number} [threshold] - Coverage threshold to use (defaults to COVERAGE_THRESHOLD)
+ * @returns {{ pass: boolean, failures: Array<{ file: string, actual: number, threshold: number, metric: string }> }}
+ */
+export declare function checkCoverageThresholds(coverageData: UnsafeAny, threshold?: number): {
+    pass: boolean;
+    failures: {
+        file: string;
+        actual: number;
+        threshold: number;
+        metric: string;
+    }[];
+};
+/**
+ * Format coverage data for display.
+ *
+ * @param {object|null} coverageData - Parsed coverage data
+ * @returns {string} Formatted output string
+ */
+export declare function formatCoverageDelta(coverageData: UnsafeAny): string;
+/**
+ * Logger interface for coverage gate output
+ */
+interface CoverageGateLogger {
+    log: (...args: unknown[]) => void;
+}
+/**
+ * Options for running coverage gate
+ */
+export interface CoverageGateOptions {
+    /** Gate mode ('warn' or 'block') */
+    mode?: string;
+    /** Path to coverage JSON */
+    coveragePath?: string;
+    /** Logger for output */
+    logger?: CoverageGateLogger;
+    /**
+     * WU-1262: Coverage threshold override (0-100).
+     * When provided, overrides the default COVERAGE_THRESHOLD constant.
+     * This is typically populated from resolveCoverageConfig().
+     */
+    threshold?: number;
+}
+/**
+ * Run coverage gate.
+ *
+ * @param {CoverageGateOptions} options - Gate options
+ * @returns {Promise<{ ok: boolean, mode: string, duration: number, message: string }>}
+ */
+export declare function runCoverageGate(options?: CoverageGateOptions): Promise<{
+    ok: boolean;
+    mode: string;
+    duration: number;
+    message: string;
+}>;
+export {};
+//# sourceMappingURL=coverage-gate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-gate.d.ts","sourceRoot":"","sources":["../src/coverage-gate.ts"],"names":[],"mappings":";AAGA;;;;;;;;;;;;GAYG;AAOH;;;GAGG;AACH,eAAO,MAAM,mBAAmB;IAC9B,2CAA2C;;IAE3C,0CAA0C;;EAE1C,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,mBAG5B,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,KAAuB,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,mCAAmC,CAAC;AAEtE;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,WAQhD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,SAAS;;;SAuBxD;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,MAAM;;;;;;;;EA+BlF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,SAAS,UA6B1D;AAED;;GAEG;AACH,UAAU,kBAAkB;IAC1B,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,OAAO,GAAE,mBAAwB;;;;;GAiDtE"}

package/dist/coverage-gate.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Coverage Gate for Quality Gates
+ *
+ * WU-1433: Adds coverage checking to gates with configurable mode (warn/block).
+ * Enforces ≥90% coverage on hex core files (application layer).
+ *
+ * Mode flag allows gradual rollout:
+ * - warn: Log failures but don't block (default)
+ * - block: Fail the gate if thresholds not met
+ *
+ * @see {@link packages/@lumenflow/cli/src/gates.ts} - Integration point
+ * @see {@link vitest.config.ts} - Coverage thresholds
+ */
+/* eslint-disable security/detect-non-literal-fs-filename, security/detect-object-injection */
+import { readFileSync, existsSync } from 'node:fs';
+import { EMOJI, STRING_LITERALS } from './wu-constants.js';
+import { DEFAULT_MIN_COVERAGE } from './constants/gate-constants.js';
+/**
+ * Coverage gate modes
+ * @constant
+ */
+export const COVERAGE_GATE_MODES = Object.freeze({
+    /** Log warnings but don't fail the gate */
+    WARN: 'warn',
+    /** Fail the gate if thresholds not met */
+    BLOCK: 'block',
+});
+/**
+ * Glob patterns for hex core files that require ≥90% coverage.
+ * These are the critical application layer files.
+ *
+ * WU-1068: Changed from @exampleapp to @lumenflow for framework reusability.
+ * Project-specific patterns should be configured in workspace.yaml.
+ *
+ * @constant {string[]}
+ */
+export const HEX_CORE_PATTERNS = Object.freeze([
+    'packages/@lumenflow/core/',
+    'packages/@lumenflow/cli/',
+]);
+/**
+ * Default coverage threshold for hex core files (percentage)
+ * WU-1262: Kept for backwards compatibility.
+ * WU-2044: Now delegates to DEFAULT_MIN_COVERAGE from gate-constants.ts (DRY).
+ * The actual threshold is determined by resolveCoverageConfig() based on methodology.
+ * @constant {number}
+ */
+export const COVERAGE_THRESHOLD = DEFAULT_MIN_COVERAGE;
+/**
+ * Default path to coverage summary JSON
+ * @constant {string}
+ */
+export const DEFAULT_COVERAGE_PATH = 'coverage/coverage-summary.json';
+/**
+ * Check if a file path is in the hex core layer.
+ *
+ * WU-2448: Coverage reporters may emit absolute paths (e.g., <repo-root>/packages/...)
+ * or file:// URLs; use substring matching so hex-core checks still apply.
+ *
+ * @param {string|null|undefined} filePath - File path to check
+ * @returns {boolean} True if file is in hex core layer
+ */
+export function isHexCoreFile(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return false;
+    }
+    // Normalize backslashes to forward slashes for cross-platform compatibility
+    const normalizedPath = filePath.replace(/\\/g, '/');
+    return HEX_CORE_PATTERNS.some((pattern) => normalizedPath.includes(pattern));
+}
+/**
+ * Parse coverage JSON file.
+ *
+ * @param {string} coveragePath - Path to coverage-summary.json
+ * @returns {object|null} Parsed coverage data or null if invalid
+ */
+export function parseCoverageJson(coveragePath) {
+    if (!existsSync(coveragePath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(coveragePath, { encoding: 'utf-8' });
+        const data = JSON.parse(content);
+        // Transform to consistent format
+        const files = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (key === 'total')
+                continue;
+            files[key] = value;
+        }
+        return {
+            total: data.total,
+            files,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if coverage meets thresholds for hex core files.
+ *
+ * @param {object|null} coverageData - Parsed coverage data
+ * @param {number} [threshold] - Coverage threshold to use (defaults to COVERAGE_THRESHOLD)
+ * @returns {{ pass: boolean, failures: Array<{ file: string, actual: number, threshold: number, metric: string }> }}
+ */
+export function checkCoverageThresholds(coverageData, threshold) {
+    if (!coverageData || !coverageData.files) {
+        return { pass: true, failures: [] };
+    }
+    // WU-1262: Use provided threshold or fall back to constant
+    const effectiveThreshold = threshold ?? COVERAGE_THRESHOLD;
+    const failures = [];
+    for (const [file, metricsValue] of Object.entries(coverageData.files)) {
+        if (!isHexCoreFile(file)) {
+            continue;
+        }
+        // Check lines coverage (primary metric)
+        const metrics = metricsValue;
+        const linesCoverage = metrics.lines?.pct ?? 0;
+        if (linesCoverage < effectiveThreshold) {
+            failures.push({
+                file,
+                actual: linesCoverage,
+                threshold: effectiveThreshold,
+                metric: 'lines',
+            });
+        }
+    }
+    return {
+        pass: failures.length === 0,
+        failures,
+    };
+}
+/**
+ * Format coverage data for display.
+ *
+ * @param {object|null} coverageData - Parsed coverage data
+ * @returns {string} Formatted output string
+ */
+export function formatCoverageDelta(coverageData) {
+    if (!coverageData) {
+        return '';
+    }
+    const lines = [];
+    const totalPct = coverageData.total?.lines?.pct ?? 0;
+    lines.push(`${STRING_LITERALS.NEWLINE}Coverage Summary: ${totalPct.toFixed(1)}% lines${STRING_LITERALS.NEWLINE}`);
+    // Show hex core files
+    const hexCoreFiles = Object.entries(coverageData.files || {}).filter(([file]) => isHexCoreFile(file));
+    if (hexCoreFiles.length > 0) {
+        lines.push('Hex Core Files:');
+        for (const [file, metricsValue] of hexCoreFiles) {
+            const metrics = metricsValue;
+            const pct = metrics.lines?.pct ?? 0;
+            const status = pct >= COVERAGE_THRESHOLD ? EMOJI.SUCCESS : EMOJI.FAILURE;
+            const shortFile = file.replace('packages/@lumenflow/', '');
+            lines.push(`  ${status} ${shortFile}: ${pct.toFixed(1)}%`);
+        }
+    }
+    return lines.join(STRING_LITERALS.NEWLINE);
+}
+/**
+ * Run coverage gate.
+ *
+ * @param {CoverageGateOptions} options - Gate options
+ * @returns {Promise<{ ok: boolean, mode: string, duration: number, message: string }>}
+ */
+export async function runCoverageGate(options = {}) {
+    const start = Date.now();
+    const mode = options.mode || COVERAGE_GATE_MODES.WARN;
+    const coveragePath = options.coveragePath || DEFAULT_COVERAGE_PATH;
+    const logger = options.logger && typeof options.logger.log === 'function' ? options.logger : console;
+    // WU-1262: Use provided threshold or default constant
+    const threshold = options.threshold ?? COVERAGE_THRESHOLD;
+    // Parse coverage data
+    const coverageData = parseCoverageJson(coveragePath);
+    if (!coverageData) {
+        const duration = Date.now() - start;
+        logger.log(`\n${EMOJI.WARNING} Coverage gate: No coverage data found at ${coveragePath}`);
+        logger.log('  Run tests with coverage first: pnpm test:coverage\n');
+        return { ok: true, mode, duration, message: 'No coverage data' };
+    }
+    // Check thresholds (WU-1262: pass resolved threshold)
+    const { pass, failures } = checkCoverageThresholds(coverageData, threshold);
+    // Format and display
+    const output = formatCoverageDelta(coverageData);
+    logger.log(output);
+    const duration = Date.now() - start;
+    if (!pass) {
+        logger.log(`\n${EMOJI.FAILURE} Coverage below ${threshold}% for hex core files:`);
+        for (const failure of failures) {
+            const shortFile = failure.file.replace('packages/@lumenflow/', '');
+            logger.log(`  - ${shortFile}: ${failure.actual.toFixed(1)}% (requires ${failure.threshold}%)`);
+        }
+        if (mode === COVERAGE_GATE_MODES.BLOCK) {
+            logger.log(`\n${EMOJI.FAILURE} Coverage gate FAILED (mode: block)\n`);
+            return { ok: false, mode, duration, message: 'Coverage threshold not met' };
+        }
+        else {
+            logger.log(`\n${EMOJI.WARNING} Coverage gate WARNING (mode: warn)\n`);
+            logger.log('  Note: This will become blocking in future. Fix coverage now.\n');
+            return { ok: true, mode, duration, message: 'Coverage warning' };
+        }
+    }
+    logger.log(`\n${EMOJI.SUCCESS} Coverage gate passed\n`);
+    return { ok: true, mode, duration, message: 'Coverage OK' };
+}
+//# sourceMappingURL=coverage-gate.js.map

package/dist/coverage-gate.js.map

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

package/dist/cycle-detector.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Cycle Detection Module (WU-1088)
+ *
+ * Provides cycle detection for WU dependency graphs.
+ * Extracted from @lumenflow/initiatives to break circular dependency.
+ *
+ * @module @lumenflow/core/cycle-detector
+ */
+/**
+ * WU object interface for validation and cycle detection
+ * Note: This interface is shared with @lumenflow/initiatives for backward compatibility
+ */
+export interface WUObject {
+    id?: string;
+    blocks?: string[];
+    blocked_by?: string[];
+    initiative?: string;
+    phase?: number;
+    [key: string]: unknown;
+}
+/**
+ * Result of cycle detection
+ */
+export interface CycleResult {
+    hasCycle: boolean;
+    cycles: string[][];
+}
+/**
+ * Detects circular dependencies in WU dependency graph using DFS
+ *
+ * Uses standard cycle detection: tracks visited nodes and nodes in current
+ * recursion stack. If we encounter a node already in the recursion stack,
+ * we've found a cycle.
+ *
+ * Note: This function treats both `blocks` and `blocked_by` as edges for
+ * traversal. This means if WU-A blocks WU-B, and WU-B's blocked_by includes
+ * WU-A, following both directions will find a path back to WU-A.
+ *
+ * @param wuMap - Map of WU ID to WU object
+ * @returns Cycle detection result with hasCycle boolean and cycles array
+ *
+ * @example
+ * const wuMap = new Map([
+ *   ['WU-001', { id: 'WU-001', blocks: ['WU-002'] }],
+ *   ['WU-002', { id: 'WU-002', blocks: ['WU-001'] }],
+ * ]);
+ * const result = detectCycles(wuMap);
+ * // result.hasCycle === true
+ * // result.cycles contains the cycle path
+ */
+export declare function detectCycles(wuMap: Map<string, WUObject>): CycleResult;
+//# sourceMappingURL=cycle-detector.d.ts.map

package/dist/cycle-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle-detector.d.ts","sourceRoot":"","sources":["../src/cycle-detector.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,WAAW,CAgEtE"}