@lumenflow/core 3.1.3 → 3.2.1

package/dist/error-handler.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Typed error for process exit signals from library code.
+ * WU-1538: Core modules throw this instead of calling process.exit directly.
+ * CLI entry boundaries catch this and call process.exit with the exitCode.
+ *
+ * @class ProcessExitError
+ * @extends Error
+ */
+export declare class ProcessExitError extends Error {
+    /** Process exit code to use when caught at CLI boundary */
+    exitCode: number;
+    /**
+     * Create a process exit error
+     * @param {string} message - Error message (already formatted by die() or caller)
+     * @param {number} [exitCode=1] - Process exit code
+     */
+    constructor(message: string, exitCode?: number);
+}
+/**
+ * Structured error class with error codes and details
+ * @class WUError
+ * @extends Error
+ */
+export declare class WUError extends Error {
+    /** Error code (e.g., 'WU_NOT_FOUND') */
+    code: string;
+    /** Additional error context */
+    details: Record<string, unknown>;
+    /** Suggested commands or actions to try (optional) */
+    tryNext?: string[];
+    /** Alias for details for agent-friendly access */
+    context?: Record<string, unknown>;
+    /**
+     * Create a WU error
+     * @param {string} code - Error code (e.g., 'WU_NOT_FOUND')
+     * @param {string} message - Human-readable error message
+     * @param {object} [details={}] - Additional error context
+     */
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+/**
+ * Normalize unknown thrown values into Error instances.
+ *
+ * This is the strict-mode-safe boundary helper for `catch (err: unknown)`.
+ * Consumers should call this before accessing `.message`.
+ *
+ * @param {unknown} error - Unknown thrown value
+ * @param {string} [fallbackMessage='Unknown error'] - Message used when value has no message
+ * @returns {Error} Normalized Error instance
+ */
+export declare function toError(error: unknown, fallbackMessage?: string): Error;
+/**
+ * Strict-safe helper for extracting error messages from unknown values.
+ *
+ * @param {unknown} error - Unknown thrown value
+ * @param {string} [fallbackMessage='Unknown error'] - Message used when value has no message
+ * @returns {string} Resolved error message
+ */
+export declare function getErrorMessage(error: unknown, fallbackMessage?: string): string;
+/**
+ * Throw typed error with formatted message (replaces process.exit calls)
+ * Auto-detects script name from process.argv[1] - no string literals needed!
+ *
+ * WU-1538: Now throws ProcessExitError instead of calling process.exit directly.
+ * The CLI entry boundary (runCLI) catches ProcessExitError and maps to process.exit.
+ *
+ * @param {string} message - Error message to log
+ * @param {number} [exitCode=1] - Process exit code
+ * @throws {ProcessExitError} Always throws with the formatted message and exit code
+ * @example
+ * die('WU file not found');
+ * die('Gates failed', 2);
+ */
+export declare function die(message: UnsafeAny, exitCode?: number): never;
+/**
+ * Create a WUError instance (factory function)
+ * @param {string} code - Error code
+ * @param {string} message - Error message
+ * @param {object} [details={}] - Error details
+ * @returns {WUError} Structured error instance
+ * @example
+ * throw createError('WU_NOT_FOUND', 'WU-123 not found', { id: 'WU-123' });
+ */
+export declare function createError(code: UnsafeAny, message: UnsafeAny, details?: {}): WUError;
+/**
+ * Options for creating agent-friendly errors
+ */
+export interface AgentFriendlyErrorOptions {
+    /** Array of suggested commands or actions to try */
+    tryNext?: string[];
+    /** Additional context information */
+    context?: Record<string, unknown>;
+}
+/**
+ * Create an agent-friendly error with try-next command suggestions
+ * WU-1339: Agent-friendly error messages and hints (AX3)
+ *
+ * @param {string} code - Error code from ErrorCodes
+ * @param {string} message - Human-readable error message
+ * @param {AgentFriendlyErrorOptions} options - Options object
+ * @returns {WUError} Error instance with tryNext property and context
+ * @example
+ * throw createAgentFriendlyError(
+ *   ErrorCodes.WU_NOT_FOUND,
+ *   'WU-1234 not found',
+ *   {
+ *     tryNext: ['pnpm wu:create --id WU-1234 --lane "<lane>" --title "..."'],
+ *     context: { wuId: 'WU-1234' }
+ *   }
+ * );
+ */
+export declare function createAgentFriendlyError(code: UnsafeAny, message: UnsafeAny, options?: AgentFriendlyErrorOptions): WUError;
+/**
+ * Common error codes for WU operations
+ */
+export declare const ErrorCodes: {
+    PROCESS_EXIT: string;
+    WU_NOT_FOUND: string;
+    WU_ALREADY_CLAIMED: string;
+    WU_NOT_CLAIMED: string;
+    INVALID_WU_ID: string;
+    INVALID_LANE: string;
+    GATES_FAILED: string;
+    GIT_ERROR: string;
+    VALIDATION_ERROR: string;
+    FILE_NOT_FOUND: string;
+    YAML_PARSE_ERROR: string;
+    PARSE_ERROR: string;
+    WORKTREE_ERROR: string;
+    BRANCH_ERROR: string;
+    STATE_ERROR: string;
+    SECTION_NOT_FOUND: string;
+    INTERNAL_ERROR: string;
+    RECOVERY_ERROR: string;
+    TRANSACTION_ERROR: string;
+    LOCK_ERROR: string;
+    INIT_NOT_FOUND: string;
+    INIT_ALREADY_EXISTS: string;
+    INVALID_INIT_ID: string;
+    INVALID_SLUG: string;
+    INVALID_PHASE: string;
+    DEPENDENCY_CYCLE: string;
+};
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../src/error-handler.ts"],"names":[],"mappings":"AAsCA;;;;;;;GAOG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;gBACS,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAI;CAU1C;AAED;;;;GAIG;AACH,qBAAa,OAAQ,SAAQ,KAAK;IAChC,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElC;;;;;OAKG;gBACS,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAWjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,eAAe,SAAwB,GAAG,KAAK,CActF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,eAAe,SAAwB,GAAG,MAAM,CAE/F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,SAAI,GAAG,KAAK,CAQ3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,KAAK,WAE5E;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,SAAS,EAClB,OAAO,GAAE,yBAA8B,WAexC;AAED;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BtB,CAAC"}

package/dist/error-handler.js

@@ -0,0 +1,214 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * @file error-handler.ts
+ * @description Structured error handling with error codes
+ * WU-1082: Extract shared utilities (eliminate die() duplication)
+ * WU-1006: Library-First - use path.basename() instead of manual split
+ *
+ * Replaces die() function in:
+ * - tools/wu-claim.ts
+ * - tools/wu-done.ts
+ * - tools/wu-block.ts
+ * - tools/wu-unblock.ts
+ * - tools/wu-create.ts
+ * - tools/wu-cleanup.ts
+ * - tools/gates-pre-commit.ts
+ * - tools/validate.ts
+ * - tools/guard-worktree-commit.ts
+ */
+import path from 'node:path';
+const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
+function hasMessage(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'message' in value &&
+        typeof value.message === 'string');
+}
+/**
+ * Typed error for process exit signals from library code.
+ * WU-1538: Core modules throw this instead of calling process.exit directly.
+ * CLI entry boundaries catch this and call process.exit with the exitCode.
+ *
+ * @class ProcessExitError
+ * @extends Error
+ */
+export class ProcessExitError extends Error {
+    /** Process exit code to use when caught at CLI boundary */
+    exitCode;
+    /**
+     * Create a process exit error
+     * @param {string} message - Error message (already formatted by die() or caller)
+     * @param {number} [exitCode=1] - Process exit code
+     */
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = 'ProcessExitError';
+        this.exitCode = exitCode;
+        // Maintains proper stack trace for where error was thrown (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ProcessExitError);
+        }
+    }
+}
+/**
+ * Structured error class with error codes and details
+ * @class WUError
+ * @extends Error
+ */
+export class WUError extends Error {
+    /** Error code (e.g., 'WU_NOT_FOUND') */
+    code;
+    /** Additional error context */
+    details;
+    /** Suggested commands or actions to try (optional) */
+    tryNext;
+    /** Alias for details for agent-friendly access */
+    context;
+    /**
+     * Create a WU error
+     * @param {string} code - Error code (e.g., 'WU_NOT_FOUND')
+     * @param {string} message - Human-readable error message
+     * @param {object} [details={}] - Additional error context
+     */
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = 'WUError';
+        this.code = code;
+        this.details = details;
+        // Maintains proper stack trace for where error was thrown (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, WUError);
+        }
+    }
+}
+/**
+ * Normalize unknown thrown values into Error instances.
+ *
+ * This is the strict-mode-safe boundary helper for `catch (err: unknown)`.
+ * Consumers should call this before accessing `.message`.
+ *
+ * @param {unknown} error - Unknown thrown value
+ * @param {string} [fallbackMessage='Unknown error'] - Message used when value has no message
+ * @returns {Error} Normalized Error instance
+ */
+export function toError(error, fallbackMessage = UNKNOWN_ERROR_MESSAGE) {
+    if (error instanceof Error) {
+        return error;
+    }
+    if (typeof error === 'string' && error.length > 0) {
+        return new Error(error);
+    }
+    if (hasMessage(error)) {
+        return new Error(error.message);
+    }
+    return new Error(fallbackMessage);
+}
+/**
+ * Strict-safe helper for extracting error messages from unknown values.
+ *
+ * @param {unknown} error - Unknown thrown value
+ * @param {string} [fallbackMessage='Unknown error'] - Message used when value has no message
+ * @returns {string} Resolved error message
+ */
+export function getErrorMessage(error, fallbackMessage = UNKNOWN_ERROR_MESSAGE) {
+    return toError(error, fallbackMessage).message;
+}
+/**
+ * Throw typed error with formatted message (replaces process.exit calls)
+ * Auto-detects script name from process.argv[1] - no string literals needed!
+ *
+ * WU-1538: Now throws ProcessExitError instead of calling process.exit directly.
+ * The CLI entry boundary (runCLI) catches ProcessExitError and maps to process.exit.
+ *
+ * @param {string} message - Error message to log
+ * @param {number} [exitCode=1] - Process exit code
+ * @throws {ProcessExitError} Always throws with the formatted message and exit code
+ * @example
+ * die('WU file not found');
+ * die('Gates failed', 2);
+ */
+export function die(message, exitCode = 1) {
+    // Auto-detect script name from process.argv[1] (eliminates string literal duplication)
+    // WU-1006: Use path.basename() instead of manual split (Library-First principle)
+    const scriptPath = process.argv[1] || 'unknown';
+    const scriptName = path.basename(scriptPath, '.js');
+    const formattedMessage = `[${scriptName}] ${message}`;
+    console.error(formattedMessage);
+    throw new ProcessExitError(formattedMessage, exitCode);
+}
+/**
+ * Create a WUError instance (factory function)
+ * @param {string} code - Error code
+ * @param {string} message - Error message
+ * @param {object} [details={}] - Error details
+ * @returns {WUError} Structured error instance
+ * @example
+ * throw createError('WU_NOT_FOUND', 'WU-123 not found', { id: 'WU-123' });
+ */
+export function createError(code, message, details = {}) {
+    return new WUError(code, message, details);
+}
+/**
+ * Create an agent-friendly error with try-next command suggestions
+ * WU-1339: Agent-friendly error messages and hints (AX3)
+ *
+ * @param {string} code - Error code from ErrorCodes
+ * @param {string} message - Human-readable error message
+ * @param {AgentFriendlyErrorOptions} options - Options object
+ * @returns {WUError} Error instance with tryNext property and context
+ * @example
+ * throw createAgentFriendlyError(
+ *   ErrorCodes.WU_NOT_FOUND,
+ *   'WU-1234 not found',
+ *   {
+ *     tryNext: ['pnpm wu:create --id WU-1234 --lane "<lane>" --title "..."'],
+ *     context: { wuId: 'WU-1234' }
+ *   }
+ * );
+ */
+export function createAgentFriendlyError(code, message, options = {}) {
+    const { tryNext, context = {} } = options;
+    const error = createError(code, message, context);
+    // Add tryNext suggestions if provided
+    if (tryNext && Array.isArray(tryNext) && tryNext.length > 0) {
+        error.tryNext = tryNext;
+    }
+    // Expose details as context for agent-friendly access
+    // (WUError stores context in details property, but we expose it as context for clarity)
+    error.context = error.details;
+    return error;
+}
+/**
+ * Common error codes for WU operations
+ */
+export const ErrorCodes = {
+    PROCESS_EXIT: 'PROCESS_EXIT', // WU-1538: Typed exit signal from library code
+    WU_NOT_FOUND: 'WU_NOT_FOUND',
+    WU_ALREADY_CLAIMED: 'WU_ALREADY_CLAIMED',
+    WU_NOT_CLAIMED: 'WU_NOT_CLAIMED',
+    INVALID_WU_ID: 'INVALID_WU_ID',
+    INVALID_LANE: 'INVALID_LANE',
+    GATES_FAILED: 'GATES_FAILED',
+    GIT_ERROR: 'GIT_ERROR',
+    VALIDATION_ERROR: 'VALIDATION_ERROR',
+    FILE_NOT_FOUND: 'FILE_NOT_FOUND',
+    YAML_PARSE_ERROR: 'YAML_PARSE_ERROR',
+    PARSE_ERROR: 'PARSE_ERROR',
+    WORKTREE_ERROR: 'WORKTREE_ERROR',
+    BRANCH_ERROR: 'BRANCH_ERROR',
+    STATE_ERROR: 'STATE_ERROR',
+    SECTION_NOT_FOUND: 'SECTION_NOT_FOUND',
+    INTERNAL_ERROR: 'INTERNAL_ERROR',
+    RECOVERY_ERROR: 'RECOVERY_ERROR',
+    TRANSACTION_ERROR: 'TRANSACTION_ERROR', // WU-1369: Atomic transaction errors
+    LOCK_ERROR: 'LOCK_ERROR', // WU-1747: Merge lock errors
+    // Initiative system error codes (WU-1247)
+    INIT_NOT_FOUND: 'INIT_NOT_FOUND',
+    INIT_ALREADY_EXISTS: 'INIT_ALREADY_EXISTS',
+    INVALID_INIT_ID: 'INVALID_INIT_ID',
+    INVALID_SLUG: 'INVALID_SLUG',
+    INVALID_PHASE: 'INVALID_PHASE',
+    DEPENDENCY_CYCLE: 'DEPENDENCY_CYCLE',
+};
+//# sourceMappingURL=error-handler.js.map

package/dist/error-handler.js.map

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

package/dist/file-classifiers.d.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * File Classifiers
+ *
+ * Shared utilities for classifying file types.
+ * Consolidates duplicated classification logic from wu-validator.ts
+ * and code-path-validator.ts.
+ *
+ * WU-1848: DRY Consolidation - Eliminate duplicated code patterns
+ *
+ * @see tools/lib/wu-validator.ts - Original isTestFile, isMarkdownFile
+ * @see tools/lib/code-path-validator.ts - Duplicated implementations
+ */
+/**
+ * Prefixes for paths that qualify as documentation-only.
+ * @constant {string[]}
+ */
+declare const DOCS_ONLY_PREFIXES: readonly string[];
+/**
+ * Root file patterns that qualify as docs-only.
+ * @constant {string[]}
+ */
+declare const DOCS_ONLY_ROOT_FILES: readonly string[];
+/**
+ * Test file patterns for detection
+ * @constant {RegExp[]}
+ */
+declare const TEST_FILE_PATTERNS: readonly RegExp[];
+/**
+ * Check if a file path is a test file
+ *
+ * Detects test files by extension and directory patterns:
+ * - *.test.ts, *.test.tsx, *.test.js, *.test.jsx, *.test.ts
+ * - *.spec.ts, *.spec.tsx, *.spec.js, *.spec.jsx, *.spec.ts
+ * - Files in __tests__ directories
+ * - *.test-utils.* files
+ * - *.mock.* files
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if file is a test file
+ */
+export declare function isTestFile(filePath: UnsafeAny): boolean;
+/**
+ * Check if a file path is a markdown file
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if file is a markdown file (.md extension)
+ */
+export declare function isMarkdownFile(filePath: UnsafeAny): boolean;
+/**
+ * Check if a file path is a documentation-only path
+ *
+ * Documentation paths include:
+ * - docs/, ai/, .claude/, memory-bank/ directories
+ * - README* files at root
+ * - CLAUDE*.md files at root
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if file is in a documentation path
+ */
+export declare function isDocumentationPath(filePath: UnsafeAny): boolean;
+export { DOCS_ONLY_PREFIXES, DOCS_ONLY_ROOT_FILES, TEST_FILE_PATTERNS };
+//# sourceMappingURL=file-classifiers.d.ts.map

package/dist/file-classifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-classifiers.d.ts","sourceRoot":"","sources":["../src/file-classifiers.ts"],"names":[],"mappings":";AAGA;;;;;;;;;;;GAWG;AAEH;;;GAGG;AACH,QAAA,MAAM,kBAAkB,mBAA8D,CAAC;AAEvF;;;GAGG;AACH,QAAA,MAAM,oBAAoB,mBAAsC,CAAC;AAEjE;;;GAGG;AACH,QAAA,MAAM,kBAAkB,mBAMtB,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,SAAS,WAO7C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,WAOjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,SAAS,WA6BtD;AAGD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/file-classifiers.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * File Classifiers
+ *
+ * Shared utilities for classifying file types.
+ * Consolidates duplicated classification logic from wu-validator.ts
+ * and code-path-validator.ts.
+ *
+ * WU-1848: DRY Consolidation - Eliminate duplicated code patterns
+ *
+ * @see tools/lib/wu-validator.ts - Original isTestFile, isMarkdownFile
+ * @see tools/lib/code-path-validator.ts - Duplicated implementations
+ */
+/**
+ * Prefixes for paths that qualify as documentation-only.
+ * @constant {string[]}
+ */
+const DOCS_ONLY_PREFIXES = Object.freeze(['docs/', 'ai/', '.claude/', 'memory-bank/']);
+/**
+ * Root file patterns that qualify as docs-only.
+ * @constant {string[]}
+ */
+const DOCS_ONLY_ROOT_FILES = Object.freeze(['readme', 'claude']);
+/**
+ * Test file patterns for detection
+ * @constant {RegExp[]}
+ */
+const TEST_FILE_PATTERNS = Object.freeze([
+    /\.test\.(ts|tsx|js|jsx|mjs)$/,
+    /\.spec\.(ts|tsx|js|jsx|mjs)$/,
+    /__tests__\//,
+    /\.test-utils\./,
+    /\.mock\./,
+]);
+/**
+ * Check if a file path is a test file
+ *
+ * Detects test files by extension and directory patterns:
+ * - *.test.ts, *.test.tsx, *.test.js, *.test.jsx, *.test.ts
+ * - *.spec.ts, *.spec.tsx, *.spec.js, *.spec.jsx, *.spec.ts
+ * - Files in __tests__ directories
+ * - *.test-utils.* files
+ * - *.mock.* files
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if file is a test file
+ */
+export function isTestFile(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return false;
+    }
+    // Normalise Windows paths to forward slashes
+    const normalized = filePath.replace(/\\/g, '/');
+    return TEST_FILE_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+/**
+ * Check if a file path is a markdown file
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if file is a markdown file (.md extension)
+ */
+export function isMarkdownFile(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return false;
+    }
+    // Normalise Windows paths to forward slashes
+    const normalized = filePath.replace(/\\/g, '/');
+    return /\.md$/i.test(normalized);
+}
+/**
+ * Check if a file path is a documentation-only path
+ *
+ * Documentation paths include:
+ * - docs/, ai/, .claude/, memory-bank/ directories
+ * - README* files at root
+ * - CLAUDE*.md files at root
+ *
+ * @param {string} filePath - Path to check
+ * @returns {boolean} True if file is in a documentation path
+ */
+export function isDocumentationPath(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return false;
+    }
+    const path = filePath.trim();
+    if (path.length === 0) {
+        return false;
+    }
+    // Check docs-only prefixes (docs/, ai/, .claude/, memory-bank/)
+    for (const prefix of DOCS_ONLY_PREFIXES) {
+        if (path.startsWith(prefix)) {
+            return true;
+        }
+    }
+    // Check if it's a markdown file (*.md)
+    if (isMarkdownFile(path)) {
+        // Check root file patterns (README*, CLAUDE*.md)
+        const lowerPath = path.toLowerCase();
+        for (const pattern of DOCS_ONLY_ROOT_FILES) {
+            if (lowerPath.startsWith(pattern)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+// Export constants for external use
+export { DOCS_ONLY_PREFIXES, DOCS_ONLY_ROOT_FILES, TEST_FILE_PATTERNS };
+//# sourceMappingURL=file-classifiers.js.map

package/dist/file-classifiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-classifiers.js","sourceRoot":"","sources":["../src/file-classifiers.ts"],"names":[],"mappings":";AACA,iCAAiC;AACjC,yCAAyC;AACzC;;;;;;;;;;;GAWG;AAEH;;;GAGG;AACH,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC;AAEvF;;;GAGG;AACH,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEjE;;;GAGG;AACH,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC;IACvC,8BAA8B;IAC9B,8BAA8B;IAC9B,aAAa;IACb,gBAAgB;IAChB,UAAU;CACX,CAAC,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,UAAU,CAAC,QAAmB;IAC5C,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,6CAA6C;IAC7C,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAChD,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;AACxE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,QAAmB;IAChD,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,6CAA6C;IAC7C,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAChD,OAAO,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAmB;IACrD,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,gEAAgE;IAChE,KAAK,MAAM,MAAM,IAAI,kBAAkB,EAAE,CAAC;QACxC,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,uCAAuC;IACvC,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,iDAAiD;QACjD,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QACrC,KAAK,MAAM,OAAO,IAAI,oBAAoB,EAAE,CAAC;YAC3C,IAAI,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;gBAClC,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,oCAAoC;AACpC,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/force-bypass-audit.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Environment variable names for force bypass
+ */
+export declare const FORCE_ENV_VAR = "LUMENFLOW_FORCE";
+export declare const FORCE_REASON_ENV_VAR = "LUMENFLOW_FORCE_REASON";
+/**
+ * Represents a parsed audit log entry
+ */
+export interface AuditLogEntry {
+    timestamp: string;
+    hook: string;
+    user: string;
+    branch: string;
+    reason: string;
+    cwd: string;
+}
+/**
+ * Check if LUMENFLOW_FORCE bypass is active
+ *
+ * @returns true if LUMENFLOW_FORCE=1
+ */
+export declare function shouldBypass(): boolean;
+/**
+ * Get the audit log file path
+ *
+ * @param projectRoot - Project root directory
+ * @returns Full path to the audit log file
+ */
+export declare function getAuditLogPath(projectRoot: string): string;
+/**
+ * Log a force bypass event to the audit log
+ *
+ * This function is FAIL-OPEN: if logging fails, it warns to stderr
+ * but does NOT throw or block the bypass operation.
+ *
+ * @param hookName - Name of the hook being bypassed (pre-commit, pre-push, etc.)
+ * @param projectRoot - Project root directory
+ */
+export declare function logForceBypass(hookName: string, projectRoot: string): void;
+/**
+ * Parse a single line from the audit log
+ *
+ * @param line - Raw log line
+ * @returns Parsed entry or null if invalid
+ */
+export declare function parseAuditLogLine(line: string): AuditLogEntry | null;
+//# sourceMappingURL=force-bypass-audit.d.ts.map

package/dist/force-bypass-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"force-bypass-audit.d.ts","sourceRoot":"","sources":["../src/force-bypass-audit.ts"],"names":[],"mappings":"AA0BA;;GAEG;AACH,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAC/C,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAO7D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3D;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CA2C1E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CA2BpE"}