@lumenflow/core 1.0.0

package/dist/code-paths-overlap.js

@@ -0,0 +1,245 @@
+/**
+ * Code Paths Overlap Detection
+ *
+ * Two-step algorithm for detecting code path conflicts between Work Units:
+ * 1. Static glob containment check (fast pre-filter using pattern matching)
+ * 2. Concrete file intersection (authoritative using filesystem)
+ *
+ * @module code-paths-overlap
+ */
+import { readFileSync, existsSync } from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import fg from 'fast-glob';
+import micromatch from 'micromatch';
+import { STATUS_SECTIONS, BACKLOG_SECTIONS, STRING_LITERALS } from './wu-constants.js';
+/**
+ * Check for code path overlap between two sets of glob patterns
+ *
+ * Uses two-step algorithm:
+ * - Static check: Fast pattern analysis to detect obvious containment
+ * - Concrete check: Filesystem-based expansion to find actual file intersection
+ *
+ * @param {string[]} claimingPaths - Glob patterns from WU being claimed
+ * @param {string[]} existingPaths - Glob patterns from in-progress WU
+ * @returns {{
+ *   overlaps: boolean,
+ *   type: 'none'|'concrete'|'ambiguous',
+ *   files: string[]
+ * }} Overlap detection result
+ *
+ * @example
+ * checkOverlap(['apps/web/**'], ['apps/web/prompts/**'])
+ * // => { overlaps: true, type: 'concrete', files: [...] }
+ */
+export function checkOverlap(claimingPaths, existingPaths) {
+    // Handle empty inputs
+    if (!claimingPaths || claimingPaths.length === 0) {
+        return { overlaps: false, type: 'none', files: [] };
+    }
+    if (!existingPaths || existingPaths.length === 0) {
+        return { overlaps: false, type: 'none', files: [] };
+    }
+    // Step 1: Static check (fast pre-filter)
+    // Check if any pattern pair has static containment
+    let hasStaticOverlap = false;
+    for (const claiming of claimingPaths) {
+        for (const existing of existingPaths) {
+            // Bidirectional check: A contains B OR B contains A
+            if (staticGlobContainment(claiming, existing) || staticGlobContainment(existing, claiming)) {
+                hasStaticOverlap = true;
+                break;
+            }
+        }
+        if (hasStaticOverlap)
+            break;
+    }
+    // Step 2: Concrete check (authoritative)
+    // Expand globs and find actual file intersection
+    const allFiles = new Set();
+    for (const claiming of claimingPaths) {
+        for (const existing of existingPaths) {
+            const result = concreteFileIntersection(claiming, existing);
+            if (result.overlaps) {
+                result.files.forEach((f) => allFiles.add(f));
+            }
+        }
+    }
+    const hasConcreteOverlap = allFiles.size > 0;
+    // Decision logic:
+    // - Both static and concrete → BLOCK (concrete overlap)
+    // - Static only, no concrete → WARN (ambiguous)
+    // - Neither → ALLOW (none)
+    if (hasConcreteOverlap) {
+        return {
+            overlaps: true,
+            type: 'concrete',
+            files: [...allFiles].sort(),
+        };
+    }
+    else if (hasStaticOverlap && !hasConcreteOverlap) {
+        return {
+            overlaps: false,
+            type: 'ambiguous',
+            files: [],
+        };
+    }
+    else {
+        return {
+            overlaps: false,
+            type: 'none',
+            files: [],
+        };
+    }
+}
+/**
+ * Find all in-progress WUs with overlapping code paths
+ *
+ * Reads status.md to find in-progress WUs, loads their code_paths,
+ * and checks for overlaps with the claiming WU's paths.
+ *
+ * @param {string} statusPath - Path to status.md file
+ * @param {string[]} claimingPaths - Glob patterns from WU being claimed
+ * @param {string} claimingWU - WU ID being claimed (excluded from check)
+ * @returns {{
+ *   conflicts: Array<{wuid: string, overlaps: string[]}>,
+ *   hasBlocker: boolean
+ * }} List of conflicting WUs and whether to block claim
+ *
+ * @example
+ * detectConflicts('docs/04-operations/tasks/status.md', ['apps/**'], 'WU-901')
+ * // => { conflicts: [{wuid: 'WU-900', overlaps: ['apps/web/foo.ts']}], hasBlocker: true }
+ */
+export function detectConflicts(statusPath, claimingPaths, claimingWU) {
+    // Handle empty claiming paths
+    if (!claimingPaths || claimingPaths.length === 0) {
+        return { conflicts: [], hasBlocker: false };
+    }
+    // Read status.md
+    const content = readFileSync(statusPath, { encoding: 'utf-8' });
+    const lines = content.split(STRING_LITERALS.NEWLINE);
+    // Find "## In Progress" section (handles both status.md and backlog.md formats)
+    const inProgressIdx = lines.findIndex((l) => {
+        const normalized = l.trim().toLowerCase();
+        return (normalized === STATUS_SECTIONS.IN_PROGRESS.toLowerCase() ||
+            normalized === BACKLOG_SECTIONS.IN_PROGRESS.toLowerCase() ||
+            normalized.startsWith('## in progress'));
+    });
+    if (inProgressIdx === -1) {
+        return { conflicts: [], hasBlocker: false };
+    }
+    // Find end of In Progress section (next ## heading or end of file)
+    let endIdx = lines.slice(inProgressIdx + 1).findIndex((l) => l.startsWith('## '));
+    if (endIdx === -1)
+        endIdx = lines.length - inProgressIdx - 1;
+    else
+        endIdx = inProgressIdx + 1 + endIdx;
+    // Extract section content
+    const section = lines.slice(inProgressIdx + 1, endIdx).join(STRING_LITERALS.NEWLINE);
+    // Check for "No items" marker
+    if (section.includes('No items currently in progress')) {
+        return { conflicts: [], hasBlocker: false };
+    }
+    // Extract WU IDs from links like [WU-334 — Title](wu/WU-334.yaml)
+    const wuLinkPattern = /\[([A-Z]+-\d+)\s*—\s*[^\]]+\]\([^)]+\)/gi;
+    const matches = [...section.matchAll(wuLinkPattern)];
+    if (matches.length === 0) {
+        return { conflicts: [], hasBlocker: false };
+    }
+    // Compute project root from statusPath
+    // statusPath is at docs/04-operations/tasks/status.md
+    const tasksDir = path.dirname(statusPath); // docs/04-operations/tasks
+    const operationsDir = path.dirname(tasksDir); // docs/04-operations
+    const docsDir = path.dirname(operationsDir); // docs
+    const projectRoot = path.dirname(docsDir); // project root
+    // Check each in-progress WU for overlaps
+    const conflicts = [];
+    for (const match of matches) {
+        const activeWuid = match[1]; // e.g., "WU-334"
+        // Skip claiming WU (shouldn't conflict with itself)
+        if (activeWuid === claimingWU) {
+            continue;
+        }
+        // Read WU YAML
+        const wuPath = path.join(projectRoot, 'docs', '04-operations', 'tasks', 'wu', `${activeWuid}.yaml`);
+        if (!existsSync(wuPath)) {
+            continue; // Skip if YAML doesn't exist
+        }
+        const wuContent = readFileSync(wuPath, { encoding: 'utf-8' });
+        const wuDoc = yaml.load(wuContent);
+        // Extract code_paths (skip if not defined)
+        const existingPaths = wuDoc?.code_paths;
+        if (!existingPaths || existingPaths.length === 0) {
+            continue;
+        }
+        // Check for overlap
+        const overlapResult = checkOverlap(claimingPaths, existingPaths);
+        // Only record concrete overlaps (block on real conflicts)
+        if (overlapResult.overlaps && overlapResult.type === 'concrete') {
+            conflicts.push({
+                wuid: activeWuid,
+                overlaps: overlapResult.files,
+            });
+        }
+    }
+    return {
+        conflicts,
+        hasBlocker: conflicts.length > 0,
+    };
+}
+/**
+ * Static glob containment check (internal helper)
+ *
+ * Tests if patternA contains patternB using glob semantics.
+ * Uses micromatch to convert globs to regex and test containment.
+ *
+ * @private
+ * @param {string} patternA - First glob pattern
+ * @param {string} patternB - Second glob pattern
+ * @returns {boolean} True if patternA contains patternB
+ *
+ * @example
+ * staticGlobContainment('apps/**', 'apps/web/**') // => true
+ * staticGlobContainment('apps/web/**', 'packages/**') // => false
+ */
+function staticGlobContainment(patternA, patternB) {
+    // Convert patternB to a test path by replacing wildcards
+    // Example: 'apps/web/**' → 'apps/web/test/file.ts'
+    const testPath = patternB.replace(/\*\*/g, 'test/nested').replace(/\*/g, 'testfile');
+    // Use micromatch to test if patternA would match this test path
+    // If patternA matches the test path, it contains patternB
+    return micromatch.isMatch(testPath, patternA);
+}
+/**
+ * Concrete file intersection using filesystem (internal helper)
+ *
+ * Expands glob patterns to real files using fast-glob,
+ * then computes Set intersection to find overlapping files.
+ *
+ * @private
+ * @param {string} patternA - First glob pattern
+ * @param {string} patternB - Second glob pattern
+ * @returns {{overlaps: boolean, files: string[]}} Intersection result
+ *
+ * @example
+ * concreteFileIntersection('apps/web/**', 'apps/web/prompts/**')
+ * // => { overlaps: true, files: ['apps/web/prompts/base.yaml'] }
+ */
+function concreteFileIntersection(patternA, patternB) {
+    // Expand globs to real files using fast-glob
+    // Use sync for simplicity (wu:claim is not performance-critical)
+    const filesA = new Set(fg.sync(patternA, {
+        dot: true, // Include dotfiles
+        ignore: ['node_modules/**', '.git/**'], // Exclude common bloat
+    }));
+    const filesB = new Set(fg.sync(patternB, {
+        dot: true,
+        ignore: ['node_modules/**', '.git/**'],
+    }));
+    // Compute intersection: files in both sets
+    const intersection = [...filesA].filter((file) => filesB.has(file));
+    return {
+        overlaps: intersection.length > 0,
+        files: intersection,
+    };
+}

package/dist/commands-logger.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Git Commands Logger
+ * Part of WU-630: Detective layer (Layer 3 of 4-layer defense)
+ * Part of WU-1552: Complete logging integration with user/outcome tracking
+ *
+ * Logs all git commands to .beacon/commands.log for post-execution analysis.
+ * Provides defense-in-depth even if git shim is bypassed.
+ *
+ * Log format (v2): timestamp | command | branch | worktree | user | outcome
+ * Example: 2025-10-24T10:30:00.000Z | git status | lane/operations/wu-630 | worktrees/operations-wu-630 | agent | allowed
+ *
+ * Legacy format (v1): timestamp | command | branch | worktree
+ * - Backward compatible: old entries are parsed with user='unknown' and outcome='unknown'
+ */
+/**
+ * Command logging constants (WU-1552)
+ *
+ * User types and outcome values for audit trail logging.
+ */
+export declare const COMMAND_LOG: {
+    /** User types: who initiated the command */
+    USER: {
+        AGENT: string;
+        HUMAN: string;
+        UNKNOWN: string;
+    };
+    /** Outcome values: what happened to the command */
+    OUTCOME: {
+        ALLOWED: string;
+        BLOCKED: string;
+        UNKNOWN: string;
+    };
+};
+/**
+ * Options for logging git commands (WU-1552)
+ */
+export interface LogGitCommandOptions {
+    /** User type: 'agent' | 'human' | 'unknown' */
+    user?: string;
+    /** Command outcome: 'allowed' | 'blocked' */
+    outcome?: string;
+}
+/**
+ * Log a git command to the commands log
+ * @param {string[]} args - Git command arguments (e.g., ['status'], ['add', '.'])
+ * @param {string} logPath - Path to log file (defaults to .beacon/commands.log)
+ * @param {LogGitCommandOptions} options - Additional logging options (WU-1552)
+ */
+export declare function logGitCommand(args: any, logPath?: string, options?: LogGitCommandOptions): void;
+/**
+ * Parse a log entry line into structured data
+ * Supports both v1 (4 fields) and v2 (6 fields) formats.
+ *
+ * @param {string} line - Log line to parse
+ * @returns {{timestamp: string, command: string, branch: string, worktree: string, user: string, outcome: string} | null}
+ */
+export declare function parseLogEntry(line: any): {
+    timestamp: any;
+    command: any;
+    branch: any;
+    worktree: any;
+    user: any;
+    outcome: any;
+};
+/**
+ * Scan log for violations within a session window
+ * @param {string} logPath - Path to commands log
+ * @param {number} windowMinutes - Session window in minutes (default 60)
+ * @returns {Array<{timestamp: string, command: string, branch: string, worktree: string}>}
+ */
+export declare function scanLogForViolations(logPath?: string, windowMinutes?: number): any[];
+/**
+ * Rotate log by removing entries older than retention period
+ * @param {string} logPath - Path to commands log
+ * @param {number} retentionDays - Number of days to keep (default 7)
+ */
+export declare function rotateLog(logPath?: string, retentionDays?: number): void;

package/dist/commands-logger.js

@@ -0,0 +1,254 @@
+/**
+ * Git Commands Logger
+ * Part of WU-630: Detective layer (Layer 3 of 4-layer defense)
+ * Part of WU-1552: Complete logging integration with user/outcome tracking
+ *
+ * Logs all git commands to .beacon/commands.log for post-execution analysis.
+ * Provides defense-in-depth even if git shim is bypassed.
+ *
+ * Log format (v2): timestamp | command | branch | worktree | user | outcome
+ * Example: 2025-10-24T10:30:00.000Z | git status | lane/operations/wu-630 | worktrees/operations-wu-630 | agent | allowed
+ *
+ * Legacy format (v1): timestamp | command | branch | worktree
+ * - Backward compatible: old entries are parsed with user='unknown' and outcome='unknown'
+ */
+/* eslint-disable security/detect-non-literal-fs-filename */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getCurrentBranch, isMainWorktree } from './wu-helpers.js';
+import { BEACON_PATHS, GIT_FLAGS, STRING_LITERALS } from './wu-constants.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Default log path (can be overridden for testing)
+const DEFAULT_LOG_PATH = path.resolve(__dirname, '../..', BEACON_PATHS.COMMANDS_LOG);
+// Banned patterns (same as git shim)
+const BANNED_PATTERNS = [
+    { command: 'reset', flags: [GIT_FLAGS.HARD] },
+    { command: 'stash' },
+    { command: 'clean', flags: [GIT_FLAGS.FD_SHORT, GIT_FLAGS.DF_SHORT] },
+    { command: 'checkout', flags: [GIT_FLAGS.FORCE_SHORT, GIT_FLAGS.FORCE] },
+    { command: 'push', flags: [GIT_FLAGS.FORCE, GIT_FLAGS.FORCE_SHORT] },
+];
+const BANNED_FLAGS = [GIT_FLAGS.NO_VERIFY, GIT_FLAGS.NO_GPG_SIGN];
+/**
+ * Command logging constants (WU-1552)
+ *
+ * User types and outcome values for audit trail logging.
+ */
+export const COMMAND_LOG = {
+    /** User types: who initiated the command */
+    USER: {
+        AGENT: 'agent',
+        HUMAN: 'human',
+        UNKNOWN: 'unknown',
+    },
+    /** Outcome values: what happened to the command */
+    OUTCOME: {
+        ALLOWED: 'allowed',
+        BLOCKED: 'blocked',
+        UNKNOWN: 'unknown',
+    },
+};
+/**
+ * Log a git command to the commands log
+ * @param {string[]} args - Git command arguments (e.g., ['status'], ['add', '.'])
+ * @param {string} logPath - Path to log file (defaults to .beacon/commands.log)
+ * @param {LogGitCommandOptions} options - Additional logging options (WU-1552)
+ */
+export function logGitCommand(args, logPath = DEFAULT_LOG_PATH, options = {}) {
+    try {
+        const timestamp = new Date().toISOString();
+        const command = `git ${args.join(' ')}`;
+        // Get current context
+        let branch, worktree;
+        if (process.env.TEST_MODE === 'true') {
+            branch = process.env.TEST_BRANCH || COMMAND_LOG.USER.UNKNOWN;
+            worktree = process.env.TEST_WORKTREE || COMMAND_LOG.USER.UNKNOWN;
+        }
+        else {
+            branch = getCurrentBranch();
+            worktree = isMainWorktree() ? '.' : process.cwd();
+        }
+        // WU-1552: Extract user and outcome from options with defaults
+        const user = options.user || COMMAND_LOG.USER.UNKNOWN;
+        const outcome = options.outcome || COMMAND_LOG.OUTCOME.ALLOWED;
+        // New format (v2): timestamp | command | branch | worktree | user | outcome
+        const logEntry = `${timestamp} | ${command} | ${branch} | ${worktree} | ${user} | ${outcome}\n`;
+        // Ensure .beacon directory exists
+        const logDir = path.dirname(logPath);
+        if (!fs.existsSync(logDir)) {
+            fs.mkdirSync(logDir, { recursive: true });
+        }
+        // Append to log file
+        fs.appendFileSync(logPath, logEntry, { encoding: 'utf-8' });
+    }
+    catch (error) {
+        // Don't fail git commands if logging fails
+        console.error(`[commands-logger] Warning: Failed to log command: ${error.message}`);
+    }
+}
+/**
+ * Parse a log entry line into structured data
+ * Supports both v1 (4 fields) and v2 (6 fields) formats.
+ *
+ * @param {string} line - Log line to parse
+ * @returns {{timestamp: string, command: string, branch: string, worktree: string, user: string, outcome: string} | null}
+ */
+export function parseLogEntry(line) {
+    if (!line || !line.trim()) {
+        return null;
+    }
+    // Split on " | " (with spaces) to avoid splitting commands that contain pipes
+    const parts = line.split(' | ');
+    // Minimum 4 fields required (v1 format)
+    if (parts.length < 4) {
+        return null;
+    }
+    // v2 format: timestamp | command | branch | worktree | user | outcome (6 fields)
+    // v1 format: timestamp | command | branch | worktree (4 fields)
+    // Commands may contain pipes, so we need to handle variable field counts
+    const hasUserOutcome = parts.length >= 6;
+    if (hasUserOutcome) {
+        // v2 format: last 2 fields are user and outcome
+        const outcome = parts[parts.length - 1].trim();
+        const user = parts[parts.length - 2].trim();
+        const worktree = parts[parts.length - 3].trim();
+        const branch = parts[parts.length - 4].trim();
+        // Everything between timestamp and branch is the command (may contain pipes)
+        const command = parts
+            .slice(1, parts.length - 4)
+            .join(' | ')
+            .trim();
+        return {
+            timestamp: parts[0].trim(),
+            command,
+            branch,
+            worktree,
+            user,
+            outcome,
+        };
+    }
+    else {
+        // v1 format (backward compatibility): no user/outcome fields
+        const worktree = parts[parts.length - 1].trim();
+        const branch = parts[parts.length - 2].trim();
+        const command = parts
+            .slice(1, parts.length - 2)
+            .join(' | ')
+            .trim();
+        return {
+            timestamp: parts[0].trim(),
+            command,
+            branch,
+            worktree,
+            user: COMMAND_LOG.USER.UNKNOWN,
+            outcome: COMMAND_LOG.OUTCOME.UNKNOWN,
+        };
+    }
+}
+/**
+ * Check if a command+context is a violation
+ * @param {string} command - The git command
+ * @param {string} branch - The branch it was run on
+ * @param {string} worktree - The worktree it was run in
+ * @returns {boolean}
+ */
+function isViolation(command, branch, worktree) {
+    // Protected context: main branch OR main worktree (.)
+    const isProtected = branch === 'main' || worktree === '.';
+    if (!isProtected) {
+        return false; // Allowed on lane branches in worktrees
+    }
+    // Parse command into args
+    const args = command.replace(/^git\s+/, '').split(/\s+/);
+    const commandName = args[0]?.toLowerCase();
+    const flags = args.slice(1).map((a) => a.toLowerCase());
+    // Check banned flags
+    for (const bannedFlag of BANNED_FLAGS) {
+        if (flags.includes(bannedFlag)) {
+            return true;
+        }
+    }
+    // Check banned command patterns
+    for (const pattern of BANNED_PATTERNS) {
+        if (commandName !== pattern.command)
+            continue;
+        // If no specific flags required, ban the command entirely
+        if (!pattern.flags) {
+            return true;
+        }
+        // Check if any required flag is present
+        const hasRequiredFlag = pattern.flags.some((reqFlag) => flags.includes(reqFlag));
+        if (hasRequiredFlag) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Scan log for violations within a session window
+ * @param {string} logPath - Path to commands log
+ * @param {number} windowMinutes - Session window in minutes (default 60)
+ * @returns {Array<{timestamp: string, command: string, branch: string, worktree: string}>}
+ */
+export function scanLogForViolations(logPath = DEFAULT_LOG_PATH, windowMinutes = 60) {
+    if (!fs.existsSync(logPath)) {
+        return [];
+    }
+    try {
+        const content = fs.readFileSync(logPath, { encoding: 'utf-8' });
+        const lines = content.trim().split(STRING_LITERALS.NEWLINE).filter(Boolean);
+        const now = new Date();
+        const windowStart = new Date(now.getTime() - windowMinutes * 60 * 1000);
+        const violations = [];
+        for (const line of lines) {
+            const entry = parseLogEntry(line);
+            if (!entry)
+                continue;
+            // Filter by session window
+            const entryTime = new Date(entry.timestamp);
+            if (entryTime < windowStart) {
+                continue;
+            }
+            // Check if this is a violation
+            if (isViolation(entry.command, entry.branch, entry.worktree)) {
+                violations.push(entry);
+            }
+        }
+        return violations;
+    }
+    catch (error) {
+        console.error(`[commands-logger] Warning: Failed to scan log: ${error.message}`);
+        return [];
+    }
+}
+/**
+ * Rotate log by removing entries older than retention period
+ * @param {string} logPath - Path to commands log
+ * @param {number} retentionDays - Number of days to keep (default 7)
+ */
+export function rotateLog(logPath = DEFAULT_LOG_PATH, retentionDays = 7) {
+    if (!fs.existsSync(logPath)) {
+        return;
+    }
+    try {
+        const content = fs.readFileSync(logPath, { encoding: 'utf-8' });
+        const lines = content.trim().split(STRING_LITERALS.NEWLINE).filter(Boolean);
+        const now = new Date();
+        const cutoffDate = new Date(now.getTime() - retentionDays * 24 * 60 * 60 * 1000);
+        const recentLines = lines.filter((line) => {
+            const entry = parseLogEntry(line);
+            if (!entry)
+                return false;
+            const entryTime = new Date(entry.timestamp);
+            return entryTime >= cutoffDate;
+        });
+        // Write back only recent entries
+        fs.writeFileSync(logPath, recentLines.join(STRING_LITERALS.NEWLINE) +
+            (recentLines.length > 0 ? STRING_LITERALS.NEWLINE : ''), { encoding: 'utf-8' });
+    }
+    catch (error) {
+        console.error(`[commands-logger] Warning: Failed to rotate log: ${error.message}`);
+    }
+}

package/dist/commit-message-utils.d.ts

@@ -0,0 +1,25 @@
+/**
+ * WU-2278: Commit Message Utilities
+ *
+ * Utilities for processing commit messages according to commitlint rules.
+ * Specifically handles lowercasing of commit subjects.
+ *
+ * Note: This is internal LumenFlow tooling - no external library applies.
+ *
+ * @module commit-message-utils
+ */
+/**
+ * Lowercase the entire subject of a conventional commit message
+ *
+ * commitlint requires lowercase subjects, but the prepare-commit-msg hook
+ * was only lowercasing the first character. This function lowercases
+ * the entire subject portion.
+ *
+ * Examples:
+ *   "feat(wu-100): Add Supabase integration" -> "feat(wu-100): add supabase integration"
+ *   "fix: Fix OpenAI API call" -> "fix: fix openai api call"
+ *
+ * @param {string} message - Commit message (first line only)
+ * @returns {string} Message with lowercased subject
+ */
+export declare function lowercaseCommitSubject(message: any): any;

package/dist/commit-message-utils.js

@@ -0,0 +1,41 @@
+/**
+ * WU-2278: Commit Message Utilities
+ *
+ * Utilities for processing commit messages according to commitlint rules.
+ * Specifically handles lowercasing of commit subjects.
+ *
+ * Note: This is internal LumenFlow tooling - no external library applies.
+ *
+ * @module commit-message-utils
+ */
+/**
+ * Lowercase the entire subject of a conventional commit message
+ *
+ * commitlint requires lowercase subjects, but the prepare-commit-msg hook
+ * was only lowercasing the first character. This function lowercases
+ * the entire subject portion.
+ *
+ * Examples:
+ *   "feat(wu-100): Add Supabase integration" -> "feat(wu-100): add supabase integration"
+ *   "fix: Fix OpenAI API call" -> "fix: fix openai api call"
+ *
+ * @param {string} message - Commit message (first line only)
+ * @returns {string} Message with lowercased subject
+ */
+export function lowercaseCommitSubject(message) {
+    if (!message || typeof message !== 'string') {
+        return message;
+    }
+    // Match conventional commit format: type(scope): subject
+    // or type: subject
+    // Using indexOf for simple parsing - safer than complex regex
+    const colonIndex = message.indexOf(': ');
+    if (colonIndex > 0) {
+        const prefix = message.slice(0, colonIndex);
+        const subject = message.slice(colonIndex + 2);
+        const lowercaseSubject = subject.toLowerCase();
+        return `${prefix.toLowerCase()}: ${lowercaseSubject}`;
+    }
+    // No conventional format - lowercase entire message
+    return message.toLowerCase();
+}