@lumenflow/core 1.0.0

package/dist/wu-helpers.d.ts

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * WU Helpers - Shared utilities for worktree and WU validation hooks
+ *
+ * Used by:
+ * - .husky/prepare-commit-msg
+ * - .husky/pre-commit
+ * - .husky/pre-push
+ */
+/**
+ * Validate WU ID format
+ *
+ * WU-1593: Extracted from duplicate implementations in wu-create.mjs and wu-edit.mjs (DRY).
+ * Uses centralized PATTERNS.WU_ID regex from wu-constants.mjs.
+ *
+ * @param {string} id - WU ID to validate (e.g., 'WU-123')
+ * @throws {Error} If ID format is invalid
+ *
+ * @example
+ * validateWUIDFormat('WU-123'); // OK
+ * validateWUIDFormat('wu-123'); // throws Error
+ * validateWUIDFormat('TICKET-123'); // throws Error
+ */
+export declare function validateWUIDFormat(id: any): void;
+/**
+ * Execute a shell command and return the output
+ * @param {string} cmd - Command to execute
+ * @param {object} opts - Execution options
+ * @returns {string} Command output
+ */
+export declare function run(cmd: any, opts?: {}): string;
+/**
+ * Get the current Git branch name
+ * Uses REAL_GIT to bypass shim and prevent recursion.
+ * @returns {string|null} Branch name or null if not in a git repo
+ */
+export declare function getCurrentBranch(): string;
+/**
+ * Get the current working directory relative to repo root
+ * Uses REAL_GIT to bypass shim and prevent recursion.
+ * @returns {string} Current directory path
+ */
+export declare function getCurrentDir(): string;
+/**
+ * Check if we're in the main worktree (not a lane worktree)
+ * Uses REAL_GIT to bypass shim and prevent recursion.
+ * @returns {boolean} True if in main worktree
+ */
+export declare function isMainWorktree(): boolean;
+/**
+ * Extract WU ID from branch name
+ * Expected format: lane/<lane-name>/<wu-id>
+ * @param {string} branch - Branch name
+ * @returns {string|null} WU ID (e.g., 'WU-401') or null
+ */
+export declare function extractWUFromBranch(branch: any): any;
+/**
+ * Validate branch name follows lane convention
+ * Expected: lane/<lane-name>/<wu-id>
+ * @param {string} branch - Branch name to validate
+ * @returns {{valid: boolean, lane: string|null, wuid: string|null, error: string|null}}
+ */
+export declare function validateBranchName(branch: any): {
+    valid: boolean;
+    lane: any;
+    wuid: any;
+    error: string;
+} | {
+    valid: boolean;
+    lane: any;
+    wuid: any;
+    error: any;
+};
+/**
+ * Read WU YAML file and return parsed content
+ * Uses REAL_GIT to bypass shim and prevent recursion.
+ * @param {string} wuid - WU ID (e.g., 'WU-401')
+ * @returns {object|null} Parsed WU YAML or null if not found
+ */
+export declare function readWUYaml(wuid: any): any;
+/**
+ * Check if WU status allows the operation
+ * @param {string} wuid - WU ID
+ * @param {string[]} allowedStatuses - List of allowed statuses
+ * @returns {{allowed: boolean, status: string|null, error: string|null}}
+ */
+export declare function checkWUStatus(wuid: any, allowedStatuses?: string[]): {
+    allowed: boolean;
+    status: any;
+    error: string;
+};
+/**
+ * Format an error message for hook output
+ * @param {string} hookName - Name of the hook
+ * @param {string} message - Error message
+ * @returns {string} Formatted error message
+ */
+export declare function formatHookError(hookName: any, message: any): string;
+/**
+ * Extract WU ID from commit message
+ * Supports formats:
+ * - wu(WU-401): message
+ * - chore(wu-401): message
+ * - feat(wu-401): message
+ * @param {string} message - Commit message
+ * @returns {string|null} WU ID or null
+ */
+export declare function extractWUFromCommitMessage(message: any): any;
+/**
+ * Ensure current branch is main. Throws if not.
+ *
+ * Centralized from duplicated ensureOnMain() functions across wu-* scripts (WU-1256).
+ * Async version - accepts a git adapter with async getCurrentBranch() method.
+ *
+ * @param {object} git - Git adapter with async getCurrentBranch() method
+ * @throws {Error} If not on main branch
+ */
+export declare function ensureOnMain(git: any): Promise<void>;
+/**
+ * Ensure main branch is up to date with origin.
+ *
+ * Centralized from duplicated ensureMainUpToDate() functions across wu-* scripts (WU-1256).
+ *
+ * @param {object} git - Git adapter with async fetch() and getCommitHash() methods
+ * @param {string} [scriptName='wu'] - Script name for logging
+ * @throws {Error} If main is out of sync with origin
+ */
+export declare function ensureMainUpToDate(git: any, _scriptName?: string): Promise<void>;

package/dist/wu-helpers.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/**
+ * WU Helpers - Shared utilities for worktree and WU validation hooks
+ *
+ * Used by:
+ * - .husky/prepare-commit-msg
+ * - .husky/pre-commit
+ * - .husky/pre-push
+ */
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parse } from 'yaml';
+import { BRANCHES, REMOTES, STDIO, REAL_GIT, PATTERNS } from './wu-constants.js';
+import { die } from './error-handler.js';
+/**
+ * Validate WU ID format
+ *
+ * WU-1593: Extracted from duplicate implementations in wu-create.mjs and wu-edit.mjs (DRY).
+ * Uses centralized PATTERNS.WU_ID regex from wu-constants.mjs.
+ *
+ * @param {string} id - WU ID to validate (e.g., 'WU-123')
+ * @throws {Error} If ID format is invalid
+ *
+ * @example
+ * validateWUIDFormat('WU-123'); // OK
+ * validateWUIDFormat('wu-123'); // throws Error
+ * validateWUIDFormat('TICKET-123'); // throws Error
+ */
+export function validateWUIDFormat(id) {
+    if (!PATTERNS.WU_ID.test(id)) {
+        die(`Invalid WU ID format: "${id}"\n\nExpected format: WU-<number> (e.g., WU-706)`);
+    }
+}
+/**
+ * Execute a shell command and return the output
+ * @param {string} cmd - Command to execute
+ * @param {object} opts - Execution options
+ * @returns {string} Command output
+ */
+export function run(cmd, opts = {}) {
+    try {
+        return execSync(cmd, { stdio: STDIO.PIPE, encoding: 'utf-8', ...opts }).trim();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Get the current Git branch name
+ * Uses REAL_GIT to bypass shim and prevent recursion.
+ * @returns {string|null} Branch name or null if not in a git repo
+ */
+export function getCurrentBranch() {
+    return run(`${REAL_GIT} rev-parse --abbrev-ref HEAD`) || null;
+}
+/**
+ * Get the current working directory relative to repo root
+ * Uses REAL_GIT to bypass shim and prevent recursion.
+ * @returns {string} Current directory path
+ */
+export function getCurrentDir() {
+    const repoRoot = run(`${REAL_GIT} rev-parse --show-toplevel`);
+    const cwd = process.cwd();
+    if (!repoRoot)
+        return cwd;
+    return path.relative(repoRoot, cwd) || '.';
+}
+/**
+ * Check if we're in the main worktree (not a lane worktree)
+ * Uses REAL_GIT to bypass shim and prevent recursion.
+ * @returns {boolean} True if in main worktree
+ */
+export function isMainWorktree() {
+    const gitDir = run(`${REAL_GIT} rev-parse --git-dir`);
+    if (!gitDir)
+        return true;
+    const normalized = gitDir.replace(/\\/g, '/');
+    // Lane worktrees live under .git/worktrees/<name>
+    return !normalized.includes('/worktrees/');
+}
+/**
+ * Extract WU ID from branch name
+ * Expected format: lane/<lane-name>/<wu-id>
+ * @param {string} branch - Branch name
+ * @returns {string|null} WU ID (e.g., 'WU-401') or null
+ */
+export function extractWUFromBranch(branch) {
+    if (!branch)
+        return null;
+    // Match lane/<lane>/<wu-id> format
+    const match = branch.match(/^lane\/[^/]+\/(wu-\d+)$/i);
+    if (match) {
+        return match[1].toUpperCase();
+    }
+    return null;
+}
+/**
+ * Validate branch name follows lane convention
+ * Expected: lane/<lane-name>/<wu-id>
+ * @param {string} branch - Branch name to validate
+ * @returns {{valid: boolean, lane: string|null, wuid: string|null, error: string|null}}
+ */
+export function validateBranchName(branch) {
+    if (!branch || branch === BRANCHES.MAIN) {
+        return { valid: true, lane: null, wuid: null, error: null };
+    }
+    const match = branch.match(/^lane\/([^/]+)\/(wu-\d+)$/i);
+    if (!match) {
+        return {
+            valid: false,
+            lane: null,
+            wuid: null,
+            error: `Branch '${branch}' doesn't follow lane/<lane>/<wu-id> convention`,
+        };
+    }
+    return {
+        valid: true,
+        lane: match[1],
+        wuid: match[2].toUpperCase(),
+        error: null,
+    };
+}
+/**
+ * Read WU YAML file and return parsed content
+ * Uses REAL_GIT to bypass shim and prevent recursion.
+ * @param {string} wuid - WU ID (e.g., 'WU-401')
+ * @returns {object|null} Parsed WU YAML or null if not found
+ */
+export function readWUYaml(wuid) {
+    const repoRoot = run(`${REAL_GIT} rev-parse --show-toplevel`);
+    if (!repoRoot)
+        return null;
+    const wuPath = path.join(repoRoot, 'docs', '04-operations', 'tasks', 'wu', `${wuid}.yaml`);
+    if (!existsSync(wuPath))
+        return null;
+    try {
+        const content = readFileSync(wuPath, { encoding: 'utf-8' });
+        return parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if WU status allows the operation
+ * @param {string} wuid - WU ID
+ * @param {string[]} allowedStatuses - List of allowed statuses
+ * @returns {{allowed: boolean, status: string|null, error: string|null}}
+ */
+export function checkWUStatus(wuid, allowedStatuses = ['in_progress', 'waiting']) {
+    const wu = readWUYaml(wuid);
+    if (!wu) {
+        return {
+            allowed: false,
+            status: null,
+            error: `WU ${wuid} not found in docs/04-operations/tasks/wu/`,
+        };
+    }
+    const status = wu.status;
+    if (!status) {
+        return {
+            allowed: false,
+            status: null,
+            error: `WU ${wuid} has no status field`,
+        };
+    }
+    if (!allowedStatuses.includes(status)) {
+        return {
+            allowed: false,
+            status,
+            error: `WU ${wuid} status is '${status}' (expected one of: ${allowedStatuses.join(', ')})`,
+        };
+    }
+    return { allowed: true, status, error: null };
+}
+/**
+ * Format an error message for hook output
+ * @param {string} hookName - Name of the hook
+ * @param {string} message - Error message
+ * @returns {string} Formatted error message
+ */
+export function formatHookError(hookName, message) {
+    return `
+╔═══════════════════════════════════════════════════════════════════╗
+║  ${hookName.toUpperCase()} HOOK ERROR
+╠═══════════════════════════════════════════════════════════════════╣
+║  ${message}
+╚═══════════════════════════════════════════════════════════════════╝
+`;
+}
+/**
+ * Extract WU ID from commit message
+ * Supports formats:
+ * - wu(WU-401): message
+ * - chore(wu-401): message
+ * - feat(wu-401): message
+ * @param {string} message - Commit message
+ * @returns {string|null} WU ID or null
+ */
+export function extractWUFromCommitMessage(message) {
+    if (!message)
+        return null;
+    // Match wu(WU-401) or type(wu-401) patterns
+    const patterns = [
+        /wu\((wu-\d+)\)/i, // wu(WU-401)
+        /\w+\((wu-\d+)\)/i, // chore(wu-401), feat(wu-401), etc.
+    ];
+    for (const pattern of patterns) {
+        const match = message.match(pattern);
+        if (match) {
+            return match[1].toUpperCase();
+        }
+    }
+    return null;
+}
+/**
+ * Ensure current branch is main. Throws if not.
+ *
+ * Centralized from duplicated ensureOnMain() functions across wu-* scripts (WU-1256).
+ * Async version - accepts a git adapter with async getCurrentBranch() method.
+ *
+ * @param {object} git - Git adapter with async getCurrentBranch() method
+ * @throws {Error} If not on main branch
+ */
+export async function ensureOnMain(git) {
+    const branch = await git.getCurrentBranch();
+    if (branch !== BRANCHES.MAIN) {
+        throw new Error(`Run from shared checkout on '${BRANCHES.MAIN}' (found '${branch}')`);
+    }
+}
+/**
+ * Ensure main branch is up to date with origin.
+ *
+ * Centralized from duplicated ensureMainUpToDate() functions across wu-* scripts (WU-1256).
+ *
+ * @param {object} git - Git adapter with async fetch() and getCommitHash() methods
+ * @param {string} [scriptName='wu'] - Script name for logging
+ * @throws {Error} If main is out of sync with origin
+ */
+export async function ensureMainUpToDate(git, _scriptName = 'wu') {
+    await git.fetch(REMOTES.ORIGIN, BRANCHES.MAIN);
+    const localMain = await git.getCommitHash(BRANCHES.MAIN);
+    const remoteMain = await git.getCommitHash(`${REMOTES.ORIGIN}/${BRANCHES.MAIN}`);
+    if (localMain !== remoteMain) {
+        throw new Error(`Main branch is out of sync with origin.\n\nRun: git pull ${REMOTES.ORIGIN} ${BRANCHES.MAIN}`);
+    }
+}

package/dist/wu-lint.d.ts

@@ -0,0 +1,70 @@
+/**
+ * WU Spec Linter (WU-2252)
+ *
+ * Validates WU specs against two critical rules:
+ * 1. Acceptance criteria cannot reference file paths absent from code_paths
+ * 2. Acceptance/code_paths cannot conflict with invariants.yml
+ *
+ * This prevents specs that create work contradicting prior fixes.
+ *
+ * @module tools/lib/wu-lint
+ */
+/**
+ * Error type constants for WU spec linting
+ */
+export declare const WU_LINT_ERROR_TYPES: {
+    ACCEPTANCE_PATH_NOT_IN_CODE_PATHS: string;
+    CODE_PATH_CONFLICTS_INVARIANT: string;
+    ACCEPTANCE_CONFLICTS_INVARIANT: string;
+};
+/**
+ * Validate that acceptance criteria only reference paths in code_paths
+ *
+ * @param {object} wu - WU spec object
+ * @param {string} wu.id - WU ID
+ * @param {string[]} wu.acceptance - Acceptance criteria
+ * @param {string[]} wu.code_paths - Code paths
+ * @returns {{valid: boolean, errors: Array<object>}} Validation result
+ */
+export declare function validateAcceptanceCodePaths(wu: any): {
+    valid: boolean;
+    errors: any[];
+};
+/**
+ * Validate that code_paths and acceptance do not conflict with invariants
+ *
+ * @param {object} wu - WU spec object
+ * @param {Array<object>} invariants - Array of invariant definitions
+ * @returns {{valid: boolean, errors: Array<object>}} Validation result
+ */
+export declare function validateInvariantsCompliance(wu: any, invariants: any): {
+    valid: boolean;
+    errors: any[];
+};
+/**
+ * Options for linting WU spec
+ */
+export interface LintWUSpecOptions {
+    /** Pre-loaded invariants */
+    invariants?: unknown[];
+    /** Path to invariants.yml */
+    invariantsPath?: string;
+}
+/**
+ * Lint a WU spec against all rules
+ *
+ * @param {object} wu - WU spec object
+ * @param {LintWUSpecOptions} [options={}] - Options
+ * @returns {{valid: boolean, errors: Array<object>}} Lint result
+ */
+export declare function lintWUSpec(wu: any, options?: LintWUSpecOptions): {
+    valid: boolean;
+    errors: any[];
+};
+/**
+ * Format lint errors for display
+ *
+ * @param {Array<object>} errors - Array of lint errors
+ * @returns {string} Formatted error message
+ */
+export declare function formatLintErrors(errors: any): string;

package/dist/wu-lint.js

@@ -0,0 +1,234 @@
+/**
+ * WU Spec Linter (WU-2252)
+ *
+ * Validates WU specs against two critical rules:
+ * 1. Acceptance criteria cannot reference file paths absent from code_paths
+ * 2. Acceptance/code_paths cannot conflict with invariants.yml
+ *
+ * This prevents specs that create work contradicting prior fixes.
+ *
+ * @module tools/lib/wu-lint
+ */
+import { existsSync } from 'node:fs';
+import { minimatch } from 'minimatch';
+import { loadInvariants, INVARIANT_TYPES } from './invariants-runner.js';
+/**
+ * Error type constants for WU spec linting
+ */
+export const WU_LINT_ERROR_TYPES = {
+    ACCEPTANCE_PATH_NOT_IN_CODE_PATHS: 'acceptance_path_not_in_code_paths',
+    CODE_PATH_CONFLICTS_INVARIANT: 'code_path_conflicts_invariant',
+    ACCEPTANCE_CONFLICTS_INVARIANT: 'acceptance_conflicts_invariant',
+};
+/**
+ * Regex to detect file paths in acceptance criteria text
+ * Matches patterns like: apps/web/src/file.ts, tools/lib/helper.mjs
+ * Uses explicit character sets to avoid regex backtracking issues
+ */
+const FILE_PATH_PATTERN = /(?:^|[\s'"`])([a-zA-Z0-9_-]+\/[a-zA-Z0-9_./-]+\.[a-zA-Z0-9]+)/g;
+/**
+ * Extract file paths from acceptance criteria text
+ *
+ * @param {string} text - Acceptance criterion text
+ * @returns {string[]} Array of file paths found
+ */
+function extractFilePaths(text) {
+    const paths = [];
+    let match;
+    while ((match = FILE_PATH_PATTERN.exec(text)) !== null) {
+        paths.push(match[1]);
+    }
+    // Reset regex state
+    FILE_PATH_PATTERN.lastIndex = 0;
+    return paths;
+}
+/**
+ * Check if a file path matches any pattern in code_paths
+ * Supports glob patterns (e.g., apps/web/src/**\/*.ts)
+ *
+ * @param {string} filePath - File path to check
+ * @param {string[]} codePaths - Array of code_paths (may include globs)
+ * @returns {boolean} True if path matches any code_paths pattern
+ */
+function pathMatchesCodePaths(filePath, codePaths) {
+    for (const pattern of codePaths) {
+        // Exact match
+        if (filePath === pattern) {
+            return true;
+        }
+        // Glob match
+        if (minimatch(filePath, pattern)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Validate that acceptance criteria only reference paths in code_paths
+ *
+ * @param {object} wu - WU spec object
+ * @param {string} wu.id - WU ID
+ * @param {string[]} wu.acceptance - Acceptance criteria
+ * @param {string[]} wu.code_paths - Code paths
+ * @returns {{valid: boolean, errors: Array<object>}} Validation result
+ */
+export function validateAcceptanceCodePaths(wu) {
+    const { id, acceptance = [], code_paths = [] } = wu;
+    const errors = [];
+    for (const criterion of acceptance) {
+        const referencedPaths = extractFilePaths(criterion);
+        for (const referencedPath of referencedPaths) {
+            if (!pathMatchesCodePaths(referencedPath, code_paths)) {
+                errors.push({
+                    type: WU_LINT_ERROR_TYPES.ACCEPTANCE_PATH_NOT_IN_CODE_PATHS,
+                    wuId: id,
+                    path: referencedPath,
+                    criterion,
+                    message: `Acceptance criterion references '${referencedPath}' which is not in code_paths`,
+                    suggestion: `Add '${referencedPath}' to code_paths or remove the reference from acceptance criteria`,
+                });
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Check forbidden-file invariant for conflicts
+ *
+ * @param {object} invariant - Invariant definition
+ * @param {object} wu - WU spec object
+ * @returns {Array<object>} Array of errors (empty if no conflicts)
+ */
+function checkForbiddenFileInvariant(invariant, wu) {
+    const { id, acceptance = [], code_paths = [] } = wu;
+    const errors = [];
+    // Check if code_paths includes the forbidden file
+    if (code_paths.includes(invariant.path)) {
+        errors.push({
+            type: WU_LINT_ERROR_TYPES.CODE_PATH_CONFLICTS_INVARIANT,
+            wuId: id,
+            invariantId: invariant.id,
+            path: invariant.path,
+            message: `code_paths includes '${invariant.path}' which conflicts with invariant ${invariant.id}: ${invariant.description}`,
+            suggestion: invariant.message || `Remove '${invariant.path}' from code_paths`,
+        });
+    }
+    // Check if acceptance mentions creating the forbidden file
+    for (const criterion of acceptance) {
+        if (criterion.includes(invariant.path)) {
+            errors.push({
+                type: WU_LINT_ERROR_TYPES.ACCEPTANCE_CONFLICTS_INVARIANT,
+                wuId: id,
+                invariantId: invariant.id,
+                path: invariant.path,
+                criterion,
+                message: `Acceptance criterion references forbidden file '${invariant.path}' (${invariant.id}: ${invariant.description})`,
+                suggestion: invariant.message,
+            });
+        }
+    }
+    return errors;
+}
+/**
+ * Check mutual-exclusivity invariant for conflicts
+ *
+ * @param {object} invariant - Invariant definition
+ * @param {object} wu - WU spec object
+ * @returns {Array<object>} Array of errors (empty if no conflicts)
+ */
+function checkMutualExclusivityInvariant(invariant, wu) {
+    const { id, code_paths = [] } = wu;
+    const errors = [];
+    // Check if code_paths includes multiple files from the mutual-exclusivity set
+    const conflictingPaths = invariant.paths.filter((p) => code_paths.includes(p));
+    if (conflictingPaths.length > 1) {
+        errors.push({
+            type: WU_LINT_ERROR_TYPES.CODE_PATH_CONFLICTS_INVARIANT,
+            wuId: id,
+            invariantId: invariant.id,
+            paths: conflictingPaths,
+            message: `code_paths includes multiple mutually exclusive files (${invariant.id}): ${conflictingPaths.join(', ')}`,
+            suggestion: invariant.message || `Only one of these files should exist: ${invariant.paths.join(', ')}`,
+        });
+    }
+    return errors;
+}
+/**
+ * Validate that code_paths and acceptance do not conflict with invariants
+ *
+ * @param {object} wu - WU spec object
+ * @param {Array<object>} invariants - Array of invariant definitions
+ * @returns {{valid: boolean, errors: Array<object>}} Validation result
+ */
+export function validateInvariantsCompliance(wu, invariants) {
+    const errors = [];
+    for (const invariant of invariants) {
+        if (invariant.type === INVARIANT_TYPES.FORBIDDEN_FILE) {
+            errors.push(...checkForbiddenFileInvariant(invariant, wu));
+        }
+        else if (invariant.type === INVARIANT_TYPES.MUTUAL_EXCLUSIVITY) {
+            errors.push(...checkMutualExclusivityInvariant(invariant, wu));
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Lint a WU spec against all rules
+ *
+ * @param {object} wu - WU spec object
+ * @param {LintWUSpecOptions} [options={}] - Options
+ * @returns {{valid: boolean, errors: Array<object>}} Lint result
+ */
+export function lintWUSpec(wu, options = {}) {
+    const allErrors = [];
+    // 1. Validate acceptance/code_paths consistency
+    const acceptanceResult = validateAcceptanceCodePaths(wu);
+    allErrors.push(...acceptanceResult.errors);
+    // 2. Load invariants if not provided
+    let invariants = options.invariants || [];
+    if (!options.invariants && options.invariantsPath) {
+        try {
+            if (existsSync(options.invariantsPath)) {
+                invariants = loadInvariants(options.invariantsPath);
+            }
+        }
+        catch {
+            // If invariants can't be loaded, continue without them
+        }
+    }
+    // 3. Validate invariants compliance
+    if (invariants.length > 0) {
+        const invariantsResult = validateInvariantsCompliance(wu, invariants);
+        allErrors.push(...invariantsResult.errors);
+    }
+    return {
+        valid: allErrors.length === 0,
+        errors: allErrors,
+    };
+}
+/**
+ * Format lint errors for display
+ *
+ * @param {Array<object>} errors - Array of lint errors
+ * @returns {string} Formatted error message
+ */
+export function formatLintErrors(errors) {
+    if (errors.length === 0) {
+        return '';
+    }
+    const lines = ['WU SPEC LINT ERRORS:', ''];
+    for (const error of errors) {
+        lines.push(`- ${error.message}`);
+        if (error.suggestion) {
+            lines.push(`  Fix: ${error.suggestion}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}