@lumenflow/core 2.5.1 → 2.6.0

package/dist/gates-config.d.ts

@@ -204,3 +204,75 @@ export interface TestPolicy extends CoverageConfig {
  * @returns Resolved test policy including tests_required
  */
 export declare function resolveTestPolicy(projectRoot: string): TestPolicy;
+/**
+ * WU-1356: Supported package managers type
+ * Re-exported from lumenflow-config-schema to avoid circular import
+ */
+type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';
+/**
+ * WU-1356: Supported test runners type
+ * Re-exported from lumenflow-config-schema to avoid circular import
+ */
+type TestRunner = 'vitest' | 'jest' | 'mocha';
+/**
+ * WU-1356: Gates commands configuration type
+ */
+export interface GatesCommands {
+    test_full: string;
+    test_docs_only: string;
+    test_incremental: string;
+    lint?: string;
+    typecheck?: string;
+    format?: string;
+}
+/**
+ * WU-1356: Resolve package manager from configuration
+ *
+ * Reads the package_manager field from .lumenflow.config.yaml.
+ * Returns 'pnpm' as default if not configured.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Resolved package manager ('pnpm', 'npm', 'yarn', or 'bun')
+ */
+export declare function resolvePackageManager(projectRoot: string): PackageManager;
+/**
+ * WU-1356: Resolve test runner from configuration
+ *
+ * Reads the test_runner field from .lumenflow.config.yaml.
+ * Returns 'vitest' as default if not configured.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Resolved test runner ('vitest', 'jest', or 'mocha')
+ */
+export declare function resolveTestRunner(projectRoot: string): TestRunner;
+/**
+ * WU-1356: Resolve build command from configuration
+ *
+ * Reads the build_command field from .lumenflow.config.yaml.
+ * If not configured, uses default based on package_manager.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Resolved build command
+ */
+export declare function resolveBuildCommand(projectRoot: string): string;
+/**
+ * WU-1356: Resolve gates commands from configuration
+ *
+ * Reads gates.commands from .lumenflow.config.yaml.
+ * Merges with defaults based on package_manager if not fully specified.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Resolved gates commands configuration
+ */
+export declare function resolveGatesCommands(projectRoot: string): GatesCommands;
+/**
+ * WU-1356: Get ignore patterns for test runner
+ *
+ * Returns patterns to ignore when detecting changed tests,
+ * based on the test runner configuration.
+ *
+ * @param testRunner - Test runner type (vitest, jest, mocha)
+ * @returns Array of ignore patterns
+ */
+export declare function getIgnorePatterns(testRunner: TestRunner): string[];
+export {};

package/dist/gates-config.js

@@ -453,3 +453,193 @@ export function resolveTestPolicy(projectRoot) {
         tests_required: policy.tests_required,
     };
 }
+/**
+ * WU-1356: Default gates commands by package manager
+ *
+ * Provides sensible defaults for different package manager and test runner combinations.
+ */
+const DEFAULT_GATES_COMMANDS = {
+    pnpm: {
+        test_full: 'pnpm turbo run test',
+        test_docs_only: '',
+        test_incremental: 'pnpm vitest run --changed origin/main',
+        lint: 'pnpm lint',
+        typecheck: 'pnpm typecheck',
+        format: 'pnpm format:check',
+    },
+    npm: {
+        test_full: 'npm test',
+        test_docs_only: '',
+        test_incremental: 'npm test -- --onlyChanged',
+        lint: 'npm run lint',
+        typecheck: 'npm run typecheck',
+        format: 'npm run format:check',
+    },
+    yarn: {
+        test_full: 'yarn test',
+        test_docs_only: '',
+        test_incremental: 'yarn test --onlyChanged',
+        lint: 'yarn lint',
+        typecheck: 'yarn typecheck',
+        format: 'yarn format:check',
+    },
+    bun: {
+        test_full: 'bun test',
+        test_docs_only: '',
+        test_incremental: 'bun test --changed',
+        lint: 'bun run lint',
+        typecheck: 'bun run typecheck',
+        format: 'bun run format:check',
+    },
+};
+/**
+ * WU-1356: Default build commands by package manager
+ */
+const DEFAULT_BUILD_COMMANDS = {
+    pnpm: 'pnpm --filter @lumenflow/cli build',
+    npm: 'npm run build --workspace @lumenflow/cli',
+    yarn: 'yarn workspace @lumenflow/cli build',
+    bun: 'bun run --filter @lumenflow/cli build',
+};
+/**
+ * WU-1356: Ignore patterns by test runner
+ *
+ * Different test runners use different cache directories that should be ignored.
+ */
+const IGNORE_PATTERNS_BY_RUNNER = {
+    vitest: ['.turbo'],
+    jest: ['coverage', '.jest-cache'],
+    mocha: ['coverage', '.nyc_output'],
+};
+/**
+ * WU-1356: Resolve package manager from configuration
+ *
+ * Reads the package_manager field from .lumenflow.config.yaml.
+ * Returns 'pnpm' as default if not configured.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Resolved package manager ('pnpm', 'npm', 'yarn', or 'bun')
+ */
+export function resolvePackageManager(projectRoot) {
+    const configPath = path.join(projectRoot, CONFIG_FILE_NAME);
+    if (!fs.existsSync(configPath)) {
+        return 'pnpm';
+    }
+    try {
+        const content = fs.readFileSync(configPath, 'utf8');
+        const data = yaml.parse(content);
+        const pm = data?.package_manager;
+        if (pm && ['pnpm', 'npm', 'yarn', 'bun'].includes(pm)) {
+            return pm;
+        }
+        return 'pnpm';
+    }
+    catch {
+        return 'pnpm';
+    }
+}
+/**
+ * WU-1356: Resolve test runner from configuration
+ *
+ * Reads the test_runner field from .lumenflow.config.yaml.
+ * Returns 'vitest' as default if not configured.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Resolved test runner ('vitest', 'jest', or 'mocha')
+ */
+export function resolveTestRunner(projectRoot) {
+    const configPath = path.join(projectRoot, CONFIG_FILE_NAME);
+    if (!fs.existsSync(configPath)) {
+        return 'vitest';
+    }
+    try {
+        const content = fs.readFileSync(configPath, 'utf8');
+        const data = yaml.parse(content);
+        const runner = data?.test_runner;
+        if (runner && ['vitest', 'jest', 'mocha'].includes(runner)) {
+            return runner;
+        }
+        return 'vitest';
+    }
+    catch {
+        return 'vitest';
+    }
+}
+/**
+ * WU-1356: Resolve build command from configuration
+ *
+ * Reads the build_command field from .lumenflow.config.yaml.
+ * If not configured, uses default based on package_manager.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Resolved build command
+ */
+export function resolveBuildCommand(projectRoot) {
+    const configPath = path.join(projectRoot, CONFIG_FILE_NAME);
+    const defaultPm = resolvePackageManager(projectRoot);
+    if (!fs.existsSync(configPath)) {
+        return DEFAULT_BUILD_COMMANDS[defaultPm];
+    }
+    try {
+        const content = fs.readFileSync(configPath, 'utf8');
+        const data = yaml.parse(content);
+        // If explicit build_command is set, use it
+        if (data?.build_command && typeof data.build_command === 'string') {
+            return data.build_command;
+        }
+        // Otherwise, use default for the configured package manager
+        return DEFAULT_BUILD_COMMANDS[defaultPm];
+    }
+    catch {
+        return DEFAULT_BUILD_COMMANDS[defaultPm];
+    }
+}
+/**
+ * WU-1356: Resolve gates commands from configuration
+ *
+ * Reads gates.commands from .lumenflow.config.yaml.
+ * Merges with defaults based on package_manager if not fully specified.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Resolved gates commands configuration
+ */
+export function resolveGatesCommands(projectRoot) {
+    const configPath = path.join(projectRoot, CONFIG_FILE_NAME);
+    const pm = resolvePackageManager(projectRoot);
+    const defaults = DEFAULT_GATES_COMMANDS[pm];
+    if (!fs.existsSync(configPath)) {
+        return defaults;
+    }
+    try {
+        const content = fs.readFileSync(configPath, 'utf8');
+        const data = yaml.parse(content);
+        const commands = data?.gates?.commands;
+        if (!commands) {
+            return defaults;
+        }
+        // Merge user config with defaults (user config wins)
+        return {
+            test_full: commands.test_full ?? defaults.test_full,
+            test_docs_only: commands.test_docs_only ?? defaults.test_docs_only,
+            test_incremental: commands.test_incremental ?? defaults.test_incremental,
+            lint: commands.lint ?? defaults.lint,
+            typecheck: commands.typecheck ?? defaults.typecheck,
+            format: commands.format ?? defaults.format,
+        };
+    }
+    catch {
+        return defaults;
+    }
+}
+/**
+ * WU-1356: Get ignore patterns for test runner
+ *
+ * Returns patterns to ignore when detecting changed tests,
+ * based on the test runner configuration.
+ *
+ * @param testRunner - Test runner type (vitest, jest, mocha)
+ * @returns Array of ignore patterns
+ */
+export function getIgnorePatterns(testRunner) {
+    return IGNORE_PATTERNS_BY_RUNNER[testRunner] ?? ['.turbo'];
+}

package/dist/lumenflow-config-schema.d.ts

@@ -7,6 +7,68 @@
  * @module lumenflow-config-schema
  */
 import { z } from 'zod';
+/**
+ * WU-1356: Package manager options
+ *
+ * Supported package managers for LumenFlow CLI operations.
+ * Used for build commands, dependency installation, and script execution.
+ *
+ * @example
+ * ```yaml
+ * package_manager: npm
+ * ```
+ */
+export declare const PackageManagerSchema: z.ZodDefault<z.ZodEnum<{
+    pnpm: "pnpm";
+    npm: "npm";
+    yarn: "yarn";
+    bun: "bun";
+}>>;
+/** WU-1356: TypeScript type for package manager */
+export type PackageManager = z.infer<typeof PackageManagerSchema>;
+/**
+ * WU-1356: Test runner options
+ *
+ * Supported test runners for incremental test detection and execution.
+ * Determines how changed tests are detected and ignore patterns are derived.
+ *
+ * @example
+ * ```yaml
+ * test_runner: jest
+ * ```
+ */
+export declare const TestRunnerSchema: z.ZodDefault<z.ZodEnum<{
+    vitest: "vitest";
+    jest: "jest";
+    mocha: "mocha";
+}>>;
+/** WU-1356: TypeScript type for test runner */
+export type TestRunner = z.infer<typeof TestRunnerSchema>;
+/**
+ * WU-1356: Gates commands configuration
+ *
+ * Configurable test commands for gates execution.
+ * Replaces hard-coded turbo/vitest commands with user-configurable alternatives.
+ *
+ * @example
+ * ```yaml
+ * gates:
+ *   commands:
+ *     test_full: 'npm test'
+ *     test_docs_only: 'npm test -- --testPathPattern=docs'
+ *     test_incremental: 'npm test -- --onlyChanged'
+ * ```
+ */
+export declare const GatesCommandsConfigSchema: z.ZodObject<{
+    test_full: z.ZodDefault<z.ZodString>;
+    test_docs_only: z.ZodDefault<z.ZodString>;
+    test_incremental: z.ZodDefault<z.ZodString>;
+    lint: z.ZodOptional<z.ZodString>;
+    typecheck: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** WU-1356: TypeScript type for gates commands config */
+export type GatesCommandsConfig = z.infer<typeof GatesCommandsConfigSchema>;
 /**
  * WU-1325: Lock policy for lane-level WIP enforcement
  *
@@ -172,6 +234,20 @@ export declare const GatesConfigSchema: z.ZodObject<{
             threshold: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>]>>;
     }, z.core.$strip>>;
+    commands: z.ZodDefault<z.ZodObject<{
+        test_full: z.ZodDefault<z.ZodString>;
+        test_docs_only: z.ZodDefault<z.ZodString>;
+        test_incremental: z.ZodDefault<z.ZodString>;
+        lint: z.ZodOptional<z.ZodString>;
+        typecheck: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    ignore_patterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    lane_health: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        off: "off";
+        warn: "warn";
+    }>>;
 }, z.core.$strip>;
 /**
  * WU-1203: Progress signals configuration for sub-agent coordination
@@ -550,6 +626,20 @@ export declare const LumenFlowConfigSchema: z.ZodObject<{
                 threshold: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>]>>;
         }, z.core.$strip>>;
+        commands: z.ZodDefault<z.ZodObject<{
+            test_full: z.ZodDefault<z.ZodString>;
+            test_docs_only: z.ZodDefault<z.ZodString>;
+            test_incremental: z.ZodDefault<z.ZodString>;
+            lint: z.ZodOptional<z.ZodString>;
+            typecheck: z.ZodOptional<z.ZodString>;
+            format: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        ignore_patterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        lane_health: z.ZodDefault<z.ZodEnum<{
+            error: "error";
+            off: "off";
+            warn: "warn";
+        }>>;
     }, z.core.$strip>>;
     memory: z.ZodDefault<z.ZodObject<{
         directory: z.ZodDefault<z.ZodString>;
@@ -679,6 +769,18 @@ export declare const LumenFlowConfigSchema: z.ZodObject<{
             code_paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
+    package_manager: z.ZodDefault<z.ZodEnum<{
+        pnpm: "pnpm";
+        npm: "npm";
+        yarn: "yarn";
+        bun: "bun";
+    }>>;
+    test_runner: z.ZodDefault<z.ZodEnum<{
+        vitest: "vitest";
+        jest: "jest";
+        mocha: "mocha";
+    }>>;
+    build_command: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
 /**
  * TypeScript types inferred from schemas
@@ -787,6 +889,15 @@ export declare function validateConfig(data: unknown): z.ZodSafeParseResult<{
         minCoverage: number;
         enableSafetyCriticalTests: boolean;
         enableInvariants: boolean;
+        commands: {
+            test_full: string;
+            test_docs_only: string;
+            test_incremental: string;
+            lint?: string;
+            typecheck?: string;
+            format?: string;
+        };
+        lane_health: "error" | "off" | "warn";
         execution?: {
             preset?: string;
             setup?: string | {
@@ -819,6 +930,7 @@ export declare function validateConfig(data: unknown): z.ZodSafeParseResult<{
                 threshold?: number;
             };
         };
+        ignore_patterns?: string[];
     };
     memory: {
         directory: string;
@@ -882,6 +994,9 @@ export declare function validateConfig(data: unknown): z.ZodSafeParseResult<{
             enabled: boolean;
         };
     };
+    package_manager: "pnpm" | "npm" | "yarn" | "bun";
+    test_runner: "vitest" | "jest" | "mocha";
+    build_command: string;
     methodology?: {
         testing: "tdd" | "test-after" | "none";
         architecture: "none" | "hexagonal" | "layered";

package/dist/lumenflow-config-schema.js

@@ -11,6 +11,77 @@ import { z } from 'zod';
 import { GatesExecutionConfigSchema } from './gates-config.js';
 // WU-1259: Import methodology config schema for resolvePolicy()
 import { MethodologyConfigSchema } from './resolve-policy.js';
+/**
+ * WU-1356: Package manager options
+ *
+ * Supported package managers for LumenFlow CLI operations.
+ * Used for build commands, dependency installation, and script execution.
+ *
+ * @example
+ * ```yaml
+ * package_manager: npm
+ * ```
+ */
+export const PackageManagerSchema = z.enum(['pnpm', 'npm', 'yarn', 'bun']).default('pnpm');
+/**
+ * WU-1356: Test runner options
+ *
+ * Supported test runners for incremental test detection and execution.
+ * Determines how changed tests are detected and ignore patterns are derived.
+ *
+ * @example
+ * ```yaml
+ * test_runner: jest
+ * ```
+ */
+export const TestRunnerSchema = z.enum(['vitest', 'jest', 'mocha']).default('vitest');
+/**
+ * WU-1356: Gates commands configuration
+ *
+ * Configurable test commands for gates execution.
+ * Replaces hard-coded turbo/vitest commands with user-configurable alternatives.
+ *
+ * @example
+ * ```yaml
+ * gates:
+ *   commands:
+ *     test_full: 'npm test'
+ *     test_docs_only: 'npm test -- --testPathPattern=docs'
+ *     test_incremental: 'npm test -- --onlyChanged'
+ * ```
+ */
+export const GatesCommandsConfigSchema = z.object({
+    /**
+     * Command to run full test suite.
+     * Default: 'pnpm turbo run test'
+     */
+    test_full: z.string().default('pnpm turbo run test'),
+    /**
+     * Command to run tests in docs-only mode.
+     * Default: empty (skip tests in docs-only mode)
+     */
+    test_docs_only: z.string().default(''),
+    /**
+     * Command to run incremental tests (changed files only).
+     * Default: 'pnpm vitest run --changed origin/main'
+     */
+    test_incremental: z.string().default('pnpm vitest run --changed origin/main'),
+    /**
+     * Command to run lint checks.
+     * Default: 'pnpm lint'
+     */
+    lint: z.string().optional(),
+    /**
+     * Command to run type checks.
+     * Default: 'pnpm typecheck'
+     */
+    typecheck: z.string().optional(),
+    /**
+     * Command to run format checks.
+     * Default: 'pnpm format:check'
+     */
+    format: z.string().optional(),
+});
 /**
  * WU-1325: Lock policy for lane-level WIP enforcement
  *
@@ -306,6 +377,26 @@ export const GatesConfigSchema = z.object({
      * When set, gates runner uses these instead of hardcoded commands.
      */
     execution: GatesExecutionConfigSchema.optional(),
+    /**
+     * WU-1356: Configurable gate commands
+     * Replaces hard-coded turbo/vitest commands with user-configurable alternatives.
+     * Enables LumenFlow to work with npm/yarn/bun, Nx/plain scripts, Jest/Mocha, etc.
+     */
+    commands: GatesCommandsConfigSchema.default(() => GatesCommandsConfigSchema.parse({})),
+    /**
+     * WU-1356: Ignore patterns for test runners
+     * Patterns to ignore when detecting changed tests.
+     * Default: ['.turbo'] for vitest (derived from test_runner if not specified)
+     */
+    ignore_patterns: z.array(z.string()).optional(),
+    /**
+     * WU-1191: Lane health gate mode
+     * Controls how lane health check behaves during gates.
+     * - 'warn': Log warning if issues found (default)
+     * - 'error': Fail gates if issues found
+     * - 'off': Skip lane health check
+     */
+    lane_health: z.enum(['warn', 'error', 'off']).default('warn'),
 });
 /**
  * WU-1203: Progress signals configuration for sub-agent coordination
@@ -731,6 +822,43 @@ export const LumenFlowConfigSchema = z.object({
      * ```
      */
     lanes: LanesConfigSchema.optional(),
+    /**
+     * WU-1356: Package manager for CLI operations
+     * Determines which package manager is used for build commands,
+     * dependency installation, and script execution.
+     *
+     * @default 'pnpm'
+     *
+     * @example
+     * ```yaml
+     * package_manager: npm
+     * ```
+     */
+    package_manager: PackageManagerSchema,
+    /**
+     * WU-1356: Test runner for incremental test detection
+     * Determines how changed tests are detected and which ignore patterns to use.
+     *
+     * @default 'vitest'
+     *
+     * @example
+     * ```yaml
+     * test_runner: jest
+     * ```
+     */
+    test_runner: TestRunnerSchema,
+    /**
+     * WU-1356: Custom build command for CLI bootstrap
+     * Overrides the default build command used in cli-entry.mjs.
+     *
+     * @default 'pnpm --filter @lumenflow/cli build'
+     *
+     * @example
+     * ```yaml
+     * build_command: 'npm run build'
+     * ```
+     */
+    build_command: z.string().default('pnpm --filter @lumenflow/cli build'),
 });
 /**
  * Validate configuration data

package/dist/wu-constants.d.ts

@@ -1718,6 +1718,75 @@ export declare const CONTEXT_VALIDATION: {
         readonly GATES: "gates";
     };
 };
+/**
+ * Git hook error messages (WU-1357)
+ *
+ * Educational, structured messages for git hook blocks.
+ * Follows the "message bag" pattern: TITLE, WHY, ACTIONS, HELP, BYPASS.
+ *
+ * Design principles:
+ * - Explain WHY before showing WHAT to do
+ * - Provide multiple paths forward (not just one command)
+ * - Put emergency bypass LAST with clear warnings
+ * - Include help resources for learning
+ *
+ * @see .husky/hooks/pre-commit.mjs - Primary consumer
+ */
+export declare const HOOK_MESSAGES: {
+    /**
+     * Main branch protection block message components
+     */
+    readonly MAIN_BRANCH_BLOCK: {
+        /** Box drawing for visual structure */
+        readonly BOX: {
+            readonly TOP: "══════════════════════════════════════════════════════════════";
+            readonly DIVIDER: "──────────────────────────────────────────────────────────────";
+        };
+        /** Title shown at the top */
+        readonly TITLE: (branch: string) => string;
+        /** Educational explanation of WHY the block exists */
+        readonly WHY: {
+            readonly HEADER: "WHY THIS HAPPENS";
+            readonly LINES: readonly ["LumenFlow protects main from direct commits to ensure:", "  • All work is tracked in Work Units (WUs)", "  • Changes can be reviewed and coordinated", "  • Parallel work across lanes stays isolated"];
+        };
+        /** Action paths - multiple ways forward */
+        readonly ACTIONS: {
+            readonly HEADER: "WHAT TO DO";
+            readonly HAVE_WU: {
+                readonly HEADER: "1. If you have a Work Unit to implement:";
+                readonly COMMANDS: readonly ["pnpm wu:claim --id WU-XXXX --lane \"<Lane>\"", "cd worktrees/<lane>-wu-xxxx"];
+                readonly NOTE: "Then make your commits there";
+            };
+            readonly NEED_WU: {
+                readonly HEADER: "2. If you need to create a new Work Unit:";
+                readonly COMMANDS: readonly ["pnpm wu:create --lane \"<Lane>\" --title \"Your task\""];
+                readonly NOTE: "This generates a WU ID, then claim it as above";
+            };
+            readonly LIST_LANES: {
+                readonly HEADER: "3. Not sure what lane to use?";
+                readonly COMMANDS: readonly ["pnpm wu:list-lanes"];
+            };
+        };
+        /** Help resources */
+        readonly HELP: {
+            readonly HEADER: "NEED HELP?";
+            readonly RESOURCES: readonly ["• Read: LUMENFLOW.md (workflow overview)", "• Read: docs/04-operations/_frameworks/lumenflow/agent/onboarding/", "• Run:  pnpm wu:help"];
+        };
+        /** Emergency bypass (shown last, with warnings) */
+        readonly BYPASS: {
+            readonly HEADER: "EMERGENCY BYPASS (logged, use sparingly)";
+            readonly WARNING: "Bypasses are audit-logged. Only use for genuine emergencies.";
+            readonly COMMAND: "LUMENFLOW_FORCE=1 LUMENFLOW_FORCE_REASON=\"<reason>\" git commit ...";
+        };
+    };
+    /**
+     * Worktree discipline block message components
+     */
+    readonly WORKTREE_BLOCK: {
+        readonly TITLE: "LANE BRANCH WORK SHOULD BE IN WORKTREE";
+        readonly WHY: "Worktrees provide isolation for parallel work. Working on a lane branch from the main checkout bypasses this isolation.";
+    };
+};
 /** Type for location types */
 export type LocationType = (typeof CONTEXT_VALIDATION.LOCATION_TYPES)[keyof typeof CONTEXT_VALIDATION.LOCATION_TYPES];
 /** Type for validation error codes */

package/dist/wu-constants.js

@@ -1789,3 +1789,81 @@ export const CONTEXT_VALIDATION = {
         GATES: 'gates',
     },
 };
+/**
+ * Git hook error messages (WU-1357)
+ *
+ * Educational, structured messages for git hook blocks.
+ * Follows the "message bag" pattern: TITLE, WHY, ACTIONS, HELP, BYPASS.
+ *
+ * Design principles:
+ * - Explain WHY before showing WHAT to do
+ * - Provide multiple paths forward (not just one command)
+ * - Put emergency bypass LAST with clear warnings
+ * - Include help resources for learning
+ *
+ * @see .husky/hooks/pre-commit.mjs - Primary consumer
+ */
+export const HOOK_MESSAGES = {
+    /**
+     * Main branch protection block message components
+     */
+    MAIN_BRANCH_BLOCK: {
+        /** Box drawing for visual structure */
+        BOX: {
+            TOP: '══════════════════════════════════════════════════════════════',
+            DIVIDER: '──────────────────────────────────────────────────────────────',
+        },
+        /** Title shown at the top */
+        TITLE: (branch) => `DIRECT COMMIT TO ${branch.toUpperCase()} BLOCKED`,
+        /** Educational explanation of WHY the block exists */
+        WHY: {
+            HEADER: 'WHY THIS HAPPENS',
+            LINES: [
+                'LumenFlow protects main from direct commits to ensure:',
+                '  • All work is tracked in Work Units (WUs)',
+                '  • Changes can be reviewed and coordinated',
+                '  • Parallel work across lanes stays isolated',
+            ],
+        },
+        /** Action paths - multiple ways forward */
+        ACTIONS: {
+            HEADER: 'WHAT TO DO',
+            HAVE_WU: {
+                HEADER: '1. If you have a Work Unit to implement:',
+                COMMANDS: ['pnpm wu:claim --id WU-XXXX --lane "<Lane>"', 'cd worktrees/<lane>-wu-xxxx'],
+                NOTE: 'Then make your commits there',
+            },
+            NEED_WU: {
+                HEADER: '2. If you need to create a new Work Unit:',
+                COMMANDS: ['pnpm wu:create --lane "<Lane>" --title "Your task"'],
+                NOTE: 'This generates a WU ID, then claim it as above',
+            },
+            LIST_LANES: {
+                HEADER: '3. Not sure what lane to use?',
+                COMMANDS: ['pnpm wu:list-lanes'],
+            },
+        },
+        /** Help resources */
+        HELP: {
+            HEADER: 'NEED HELP?',
+            RESOURCES: [
+                '• Read: LUMENFLOW.md (workflow overview)',
+                '• Read: docs/04-operations/_frameworks/lumenflow/agent/onboarding/',
+                '• Run:  pnpm wu:help',
+            ],
+        },
+        /** Emergency bypass (shown last, with warnings) */
+        BYPASS: {
+            HEADER: 'EMERGENCY BYPASS (logged, use sparingly)',
+            WARNING: 'Bypasses are audit-logged. Only use for genuine emergencies.',
+            COMMAND: 'LUMENFLOW_FORCE=1 LUMENFLOW_FORCE_REASON="<reason>" git commit ...',
+        },
+    },
+    /**
+     * Worktree discipline block message components
+     */
+    WORKTREE_BLOCK: {
+        TITLE: 'LANE BRANCH WORK SHOULD BE IN WORKTREE',
+        WHY: 'Worktrees provide isolation for parallel work. Working on a lane branch from the main checkout bypasses this isolation.',
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/core",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Core WU lifecycle tools for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -99,7 +99,7 @@
     "vitest": "^4.0.17"
   },
   "peerDependencies": {
-    "@lumenflow/memory": "2.5.1"
+    "@lumenflow/memory": "2.6.0"
   },
   "peerDependenciesMeta": {
     "@lumenflow/memory": {