@lumenflow/core 2.2.0 → 2.2.2

package/dist/system-map-validator.d.ts

@@ -78,3 +78,21 @@ export declare function validateSystemMap(systemMap: any, deps: any): Promise<{
     queryErrors: any[];
     classificationErrors: any[];
 }>;
+export interface SystemMapValidationResult {
+    valid: boolean;
+    skipped: boolean;
+    pathErrors: string[];
+    orphanDocs: string[];
+    audienceErrors: string[];
+    queryErrors: string[];
+    classificationErrors: string[];
+}
+export declare function runSystemMapValidation(options?: {
+    cwd?: string;
+    systemMapPath?: string;
+    logger?: {
+        log: (message: string) => void;
+        warn?: (message: string) => void;
+        error?: (message: string) => void;
+    };
+}): Promise<SystemMapValidationResult>;

package/dist/system-map-validator.js

@@ -12,6 +12,7 @@
  * @module system-map-validator
  */
 import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
 import fg from 'fast-glob';
 import { parseYAML } from './wu-yaml.js';
 /**
@@ -274,34 +275,64 @@ export async function validateSystemMap(systemMap, deps) {
     };
 }
 const DEFAULT_SYSTEM_MAP_PATH = 'SYSTEM-MAP.yaml';
-function emitErrors(label, errors) {
-    if (!errors || errors.length === 0)
-        return;
-    console.error(`\n${label}:`);
-    for (const error of errors) {
-        console.error(`  - ${error}`);
-    }
-}
-async function runCLI() {
-    const systemMapPath = process.env.SYSTEM_MAP_PATH || DEFAULT_SYSTEM_MAP_PATH;
-    if (!existsSync(systemMapPath)) {
-        console.warn(`[system-map] ${systemMapPath} not found; skipping validation.`);
-        process.exit(0);
+export async function runSystemMapValidation(options = {}) {
+    const { cwd = process.cwd(), systemMapPath, logger = console } = options;
+    const resolvedPath = systemMapPath ?? path.join(cwd, DEFAULT_SYSTEM_MAP_PATH);
+    if (!existsSync(resolvedPath)) {
+        logger.warn?.(`[system-map] ${resolvedPath} not found; skipping validation.`);
+        return {
+            valid: true,
+            skipped: true,
+            pathErrors: [],
+            orphanDocs: [],
+            audienceErrors: [],
+            queryErrors: [],
+            classificationErrors: [],
+        };
     }
     let systemMap;
     try {
-        const raw = readFileSync(systemMapPath, 'utf-8');
+        const raw = readFileSync(resolvedPath, 'utf-8');
         systemMap = parseYAML(raw);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        console.error(`[system-map] Failed to read or parse ${systemMapPath}: ${message}`);
-        process.exit(1);
+        logger.error?.(`[system-map] Failed to read or parse ${resolvedPath}: ${message}`);
+        return {
+            valid: false,
+            skipped: false,
+            pathErrors: [message],
+            orphanDocs: [],
+            audienceErrors: [],
+            queryErrors: [],
+            classificationErrors: [],
+        };
     }
     const result = await validateSystemMap(systemMap, {
         exists: (path) => existsSync(path),
         glob: (pattern) => fg(pattern, { dot: false }),
     });
+    return {
+        valid: result.valid,
+        skipped: false,
+        pathErrors: result.pathErrors,
+        orphanDocs: result.orphanDocs,
+        audienceErrors: result.audienceErrors,
+        queryErrors: result.queryErrors,
+        classificationErrors: result.classificationErrors,
+    };
+}
+function emitErrors(label, errors) {
+    if (!errors || errors.length === 0)
+        return;
+    console.error(`\n${label}:`);
+    for (const error of errors) {
+        console.error(`  - ${error}`);
+    }
+}
+async function runCLI() {
+    const systemMapPath = process.env.SYSTEM_MAP_PATH || DEFAULT_SYSTEM_MAP_PATH;
+    const result = await runSystemMapValidation({ systemMapPath });
     if (!result.valid) {
         console.error('\n[system-map] Validation failed');
         emitErrors('Missing paths', result.pathErrors);
@@ -311,6 +342,9 @@ async function runCLI() {
         emitErrors('Classification routing violations', result.classificationErrors);
         process.exit(1);
     }
+    if (result.skipped) {
+        process.exit(0);
+    }
     console.log('[system-map] Validation passed');
     process.exit(0);
 }

package/dist/validators/backlog-sync.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @file backlog-sync.ts
+ * @description Validates backlog.md is in sync with WU YAML files (WU-1111)
+ */
+export interface BacklogSyncResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    wuCount: number;
+    backlogCount: number;
+}
+export declare function validateBacklogSync(options?: {
+    cwd?: string;
+}): Promise<BacklogSyncResult>;

package/dist/validators/backlog-sync.js

@@ -0,0 +1,60 @@
+/**
+ * @file backlog-sync.ts
+ * @description Validates backlog.md is in sync with WU YAML files (WU-1111)
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { FILE_SYSTEM } from '../wu-constants.js';
+function extractWUIDsFromBacklog(content) {
+    const wuIds = [];
+    const pattern = /WU-\d+/gi;
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+        const wuId = match[0].toUpperCase();
+        if (!wuIds.includes(wuId)) {
+            wuIds.push(wuId);
+        }
+    }
+    return wuIds;
+}
+function getWUIDsFromFiles(wuDir) {
+    if (!existsSync(wuDir)) {
+        return [];
+    }
+    return readdirSync(wuDir)
+        .filter((f) => f.endsWith('.yaml'))
+        .map((f) => f.replace('.yaml', '').toUpperCase());
+}
+export async function validateBacklogSync(options = {}) {
+    const { cwd = process.cwd() } = options;
+    const errors = [];
+    const warnings = [];
+    const backlogPath = path.join(cwd, 'docs', '04-operations', 'tasks', 'backlog.md');
+    const wuDir = path.join(cwd, 'docs', '04-operations', 'tasks', 'wu');
+    if (!existsSync(backlogPath)) {
+        errors.push(`Backlog file not found: ${backlogPath}`);
+        return { valid: false, errors, warnings, wuCount: 0, backlogCount: 0 };
+    }
+    const wuIdsFromFiles = getWUIDsFromFiles(wuDir);
+    const backlogContent = readFileSync(backlogPath, {
+        encoding: FILE_SYSTEM.UTF8,
+    });
+    const wuIdsFromBacklog = extractWUIDsFromBacklog(backlogContent);
+    for (const wuId of wuIdsFromFiles) {
+        if (!wuIdsFromBacklog.includes(wuId)) {
+            errors.push(`${wuId} not found in backlog.md (exists as ${wuId}.yaml)`);
+        }
+    }
+    for (const wuId of wuIdsFromBacklog) {
+        if (!wuIdsFromFiles.includes(wuId)) {
+            warnings.push(`${wuId} referenced in backlog.md but ${wuId}.yaml not found`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        wuCount: wuIdsFromFiles.length,
+        backlogCount: wuIdsFromBacklog.length,
+    };
+}

package/dist/validators/supabase-docs-linter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file supabase-docs-linter.ts
+ * @description Runs Supabase docs linter when available (optional in consumer repos)
+ */
+export interface SupabaseDocsLinterResult {
+    ok: boolean;
+    skipped: boolean;
+    message?: string;
+    errors?: string[];
+}
+export interface SupabaseDocsLinterOptions {
+    cwd?: string;
+    logger?: {
+        log: (message: string) => void;
+        warn?: (message: string) => void;
+    };
+}
+export declare function runSupabaseDocsLinter(options?: SupabaseDocsLinterOptions): Promise<SupabaseDocsLinterResult>;

package/dist/validators/supabase-docs-linter.js

@@ -0,0 +1,42 @@
+/**
+ * @file supabase-docs-linter.ts
+ * @description Runs Supabase docs linter when available (optional in consumer repos)
+ */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+export async function runSupabaseDocsLinter(options = {}) {
+    const { cwd = process.cwd(), logger = console } = options;
+    const linterPath = path.join(cwd, 'packages', 'linters', 'supabase-docs-linter.js');
+    if (!existsSync(linterPath)) {
+        return {
+            ok: true,
+            skipped: true,
+            message: 'Supabase docs linter not found; skipping.',
+        };
+    }
+    const moduleUrl = pathToFileURL(linterPath).href;
+    const module = await import(moduleUrl);
+    const runFn = module.runSupabaseDocsLinter ?? module.default;
+    if (typeof runFn !== 'function') {
+        return {
+            ok: false,
+            skipped: false,
+            errors: ['Supabase docs linter does not export runSupabaseDocsLinter.'],
+        };
+    }
+    const result = await runFn({ cwd, logger });
+    if (result && typeof result === 'object' && 'ok' in result) {
+        return {
+            ok: Boolean(result.ok),
+            skipped: Boolean(result.skipped),
+            message: result.message,
+            errors: result.errors,
+        };
+    }
+    return {
+        ok: true,
+        skipped: false,
+        message: 'Supabase docs linter completed.',
+    };
+}

package/dist/validators/wu-tasks.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @file wu-tasks.ts
+ * @description WU YAML validation helpers (shared by CLI and preflight)
+ */
+export interface ValidationResult {
+    valid: boolean;
+    warnings: string[];
+    errors: string[];
+}
+export interface ValidationSummary {
+    totalValid: number;
+    totalInvalid: number;
+    totalWarnings: number;
+    results: Array<{
+        wuId: string;
+    } & ValidationResult>;
+}
+export declare function validateSingleWU(wuPath: string, options?: {
+    strict?: boolean;
+}): ValidationResult;
+export declare function validateAllWUs(options?: {
+    strict?: boolean;
+    doneOnly?: boolean;
+}): ValidationSummary;

package/dist/validators/wu-tasks.js

@@ -0,0 +1,90 @@
+/**
+ * @file wu-tasks.ts
+ * @description WU YAML validation helpers (shared by CLI and preflight)
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { WU_PATHS } from '../wu-paths.js';
+import { parseYAML } from '../wu-yaml.js';
+import { validateWU, validateWUCompleteness } from '../wu-schema.js';
+import { FILE_SYSTEM } from '../wu-constants.js';
+export function validateSingleWU(wuPath, options = {}) {
+    const { strict = false } = options;
+    const errors = [];
+    const warnings = [];
+    if (!existsSync(wuPath)) {
+        errors.push(`WU file not found: ${wuPath}`);
+        return { valid: false, warnings, errors };
+    }
+    let doc;
+    try {
+        const text = readFileSync(wuPath, { encoding: FILE_SYSTEM.UTF8 });
+        doc = parseYAML(text);
+    }
+    catch (e) {
+        errors.push(`Failed to parse YAML: ${e.message}`);
+        return { valid: false, warnings, errors };
+    }
+    const schemaResult = validateWU(doc);
+    if (!schemaResult.success) {
+        const schemaErrors = schemaResult.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`);
+        errors.push(...schemaErrors);
+        return { valid: false, warnings, errors };
+    }
+    const completenessResult = validateWUCompleteness(schemaResult.data);
+    warnings.push(...completenessResult.warnings);
+    if (strict && warnings.length > 0) {
+        errors.push(...warnings.map((w) => `[STRICT] ${w}`));
+        return { valid: false, warnings: [], errors };
+    }
+    return { valid: true, warnings, errors };
+}
+export function validateAllWUs(options = {}) {
+    const { strict = false, doneOnly = false } = options;
+    const wuDir = WU_PATHS.WU_DIR();
+    if (!existsSync(wuDir)) {
+        return {
+            totalValid: 0,
+            totalInvalid: 1,
+            totalWarnings: 0,
+            results: [
+                {
+                    wuId: 'DIRECTORY',
+                    valid: false,
+                    warnings: [],
+                    errors: [`WU directory not found: ${wuDir}`],
+                },
+            ],
+        };
+    }
+    const files = readdirSync(wuDir).filter((f) => f.endsWith('.yaml'));
+    const results = [];
+    let totalValid = 0;
+    let totalInvalid = 0;
+    let totalWarnings = 0;
+    for (const file of files) {
+        const wuPath = `${wuDir}/${file}`;
+        const wuId = file.replace('.yaml', '');
+        if (doneOnly) {
+            try {
+                const text = readFileSync(wuPath, { encoding: FILE_SYSTEM.UTF8 });
+                const doc = parseYAML(text);
+                if (doc.status !== 'done') {
+                    continue;
+                }
+            }
+            catch {
+                // If we can't read, still validate to catch the error
+            }
+        }
+        const result = validateSingleWU(wuPath, { strict });
+        results.push({ wuId, ...result });
+        if (result.valid) {
+            totalValid++;
+            totalWarnings += result.warnings.length;
+        }
+        else {
+            totalInvalid++;
+        }
+    }
+    return { totalValid, totalInvalid, totalWarnings, results };
+}

package/dist/wu-constants.d.ts

@@ -958,17 +958,6 @@ export declare const GATE_COMMANDS: {
     /** WU-2062: Triggers tiered test execution based on risk */
     TIERED_TEST: string;
 };
-/**
- * Tool paths for scripts
- *
- * Centralized paths to tool scripts.
- */
-export declare const TOOL_PATHS: {
-    VALIDATE_BACKLOG_SYNC: string;
-    SUPABASE_DOCS_LINTER: string;
-    /** WU-2315: System map validator script */
-    SYSTEM_MAP_VALIDATE: string;
-};
 /**
  * CLI mode flags
  *
@@ -1186,8 +1175,6 @@ export declare const AUDIT_ARGS: {
  * Centralized paths to validation scripts.
  */
 export declare const SCRIPT_PATHS: {
-    /** WU YAML validation */
-    VALIDATE: string;
     /** Prompt registry validation */
     VALIDATE_PROMPT_REGISTRY: string;
 };

package/dist/wu-constants.js

@@ -1000,17 +1000,6 @@ export const GATE_COMMANDS = {
     /** WU-2062: Triggers tiered test execution based on risk */
     TIERED_TEST: 'tiered-test',
 };
-/**
- * Tool paths for scripts
- *
- * Centralized paths to tool scripts.
- */
-export const TOOL_PATHS = {
-    VALIDATE_BACKLOG_SYNC: 'node packages/@lumenflow/cli/dist/validate-backlog-sync.js',
-    SUPABASE_DOCS_LINTER: 'node packages/linters/supabase-docs-linter.js',
-    /** WU-2315: System map validator script */
-    SYSTEM_MAP_VALIDATE: 'node packages/@lumenflow/core/dist/system-map-validator.js',
-};
 /**
  * CLI mode flags
  *
@@ -1229,8 +1218,6 @@ export const AUDIT_ARGS = {
  * Centralized paths to validation scripts.
  */
 export const SCRIPT_PATHS = {
-    /** WU YAML validation */
-    VALIDATE: 'node packages/@lumenflow/cli/dist/validate.js',
     /** Prompt registry validation */
     VALIDATE_PROMPT_REGISTRY: 'tools/validate-prompt-registry.js',
 };

package/dist/wu-done-preflight.d.ts

@@ -1,7 +1,6 @@
 /**
  * Preflight validation helpers for wu:done.
  */
-import { execSync as execSyncImport } from 'node:child_process';
 import { validatePreflight } from './wu-preflight-validators.js';
 /**
  * WU-1781: Build preflight error message with actionable guidance
@@ -28,21 +27,24 @@ export declare function buildPreflightCodePathErrorMessage(id: any, result: any)
 /**
  * WU-1781: Run tasks:validate as preflight check before any git operations
  */
-export interface ExecSyncOverrideOptions {
-    /** Override execSync for testing (default: child_process.execSync) */
-    execSyncFn?: typeof execSyncImport;
-}
-export declare function runPreflightTasksValidation(id: any, options?: ExecSyncOverrideOptions): {
+export declare function runPreflightTasksValidation(id: any): {
     valid: boolean;
-    errors: any;
+    errors: string[];
     abortedBeforeMerge: boolean;
     localMainModified: boolean;
-    hasStampStatusError: any;
+    hasStampStatusError: boolean;
 };
 /**
  * WU-2308: Validate all pre-commit hooks with worktree context
  */
-export declare function validateAllPreCommitHooks(id: any, worktreePath?: any, options?: ExecSyncOverrideOptions): {
+export interface ValidateAllPreCommitHooksOptions {
+    runGates?: (options: {
+        cwd?: string;
+        docsOnly?: boolean;
+        wuId?: string;
+    }) => Promise<boolean>;
+}
+export declare function validateAllPreCommitHooks(id: any, worktreePath?: any, options?: ValidateAllPreCommitHooksOptions): Promise<{
     valid: boolean;
     errors: any[];
-};
+}>;

package/dist/wu-done-preflight.js

@@ -1,9 +1,10 @@
 /**
  * Preflight validation helpers for wu:done.
  */
-import { execSync as execSyncImport } from 'node:child_process';
 import { validatePreflight } from './wu-preflight-validators.js';
-import { LOG_PREFIX, EMOJI, STDIO, SCRIPT_PATHS } from './wu-constants.js';
+import { LOG_PREFIX, EMOJI } from './wu-constants.js';
+import { WU_PATHS } from './wu-paths.js';
+import { validateSingleWU } from './validators/wu-tasks.js';
 /**
  * WU-1781: Build preflight error message with actionable guidance
  */
@@ -108,17 +109,14 @@ See: docs/04-operations/_frameworks/lumenflow/agent/onboarding/troubleshooting-w
 `;
     return message;
 }
-export function runPreflightTasksValidation(id, options = {}) {
-    // Use injected execSync for testability, default to node's child_process
-    const execSyncFn = options.execSyncFn || execSyncImport;
+/**
+ * WU-1781: Run tasks:validate as preflight check before any git operations
+ */
+export function runPreflightTasksValidation(id) {
     console.log(`\n${LOG_PREFIX.DONE} 🔍 Preflight: running tasks:validate...`);
-    try {
-        // Run tasks:validate with WU_ID context (single-WU validation mode)
-        execSyncFn(SCRIPT_PATHS.VALIDATE, {
-            stdio: STDIO.PIPE,
-            encoding: 'utf-8',
-            env: { ...process.env, WU_ID: id },
-        });
+    const wuPath = WU_PATHS.WU(id);
+    const result = validateSingleWU(wuPath, { strict: false });
+    if (result.valid) {
         console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Preflight tasks:validate passed`);
         return {
             valid: true,
@@ -128,46 +126,33 @@ export function runPreflightTasksValidation(id, options = {}) {
             hasStampStatusError: false,
         };
     }
-    catch (err) {
-        // Validation failed - extract errors from output
-        const output = err.stdout || err.message || 'Unknown validation error';
-        const errors = output
-            .split('\n')
-            .filter((line) => line.includes('[') && line.includes(']'))
-            .map((line) => line.trim());
-        const hasStampStatusError = errors.some((e) => e.includes('stamp but status is not done'));
-        console.error(`\n${LOG_PREFIX.DONE} ${EMOJI.FAILURE} Preflight tasks:validate failed`);
-        return {
-            valid: false,
-            errors: errors.length > 0 ? errors : [output],
-            abortedBeforeMerge: true,
-            localMainModified: false,
-            hasStampStatusError,
-        };
-    }
+    console.error(`\n${LOG_PREFIX.DONE} ${EMOJI.FAILURE} Preflight tasks:validate failed`);
+    return {
+        valid: false,
+        errors: result.errors,
+        abortedBeforeMerge: true,
+        localMainModified: false,
+        hasStampStatusError: false,
+    };
 }
-/**
- * WU-2308: Validate all pre-commit hooks with worktree context
- */
-export function validateAllPreCommitHooks(id, worktreePath = null, options = {}) {
-    const execSyncFn = options.execSyncFn || execSyncImport;
+export async function validateAllPreCommitHooks(id, worktreePath = null, options = {}) {
     console.log(`\n${LOG_PREFIX.DONE} 🔍 Pre-flight: validating all pre-commit hooks...`);
     const errors = [];
     try {
         // WU-2308: Run from worktree context when provided to ensure audit checks
         // the worktree's dependencies (with fixes) not main's stale dependencies
-        const execOptions = {
-            stdio: STDIO.INHERIT,
-            encoding: 'utf-8',
-        };
-        // Only set cwd when worktreePath is provided
-        if (worktreePath) {
-            execOptions.cwd = worktreePath;
+        if (!options.runGates) {
+            throw new Error('runGates not provided for pre-commit validation.');
+        }
+        const ok = await options.runGates({
+            cwd: worktreePath ?? process.cwd(),
+            wuId: id,
+        });
+        if (ok) {
+            console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} All pre-commit hooks passed`);
+            return { valid: true, errors: [] };
         }
-        // WU-1139: Run CLI gates directly (removes stub scripts)
-        execSyncFn('node packages/@lumenflow/cli/dist/gates.js', execOptions);
-        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} All pre-commit hooks passed`);
-        return { valid: true, errors: [] };
+        throw new Error('Pre-commit hooks failed.');
     }
     catch {
         // Pre-commit hooks failed

package/dist/wu-done-validators.d.ts

@@ -12,4 +12,4 @@ export { applyExposureDefaults, validateCodePathsExist, validateSpecCompleteness
 export { buildPreflightErrorMessage, executePreflightCodePathValidation, buildPreflightCodePathErrorMessage, runPreflightTasksValidation, validateAllPreCommitHooks, } from './wu-done-preflight.js';
 export { validateAutomatedTestRequirement } from './manual-test-validator.js';
 export type { ValidateCodePathsExistOptions } from './wu-done-validation.js';
-export type { ExecutePreflightCodePathValidationOptions, ExecSyncOverrideOptions, } from './wu-done-preflight.js';
+export type { ExecutePreflightCodePathValidationOptions, ValidateAllPreCommitHooksOptions, } from './wu-done-preflight.js';

package/package.json

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