@lumenflow/core 1.4.0 → 1.6.0

package/dist/domain/validation.schemas.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Validation Schemas
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ *
+ * Zod schemas for validation-related types in the context-aware validation system.
+ * Types are inferred from Zod schemas using z.infer<> for single source of truth.
+ *
+ * @module domain/validation.schemas
+ */
+import { z } from 'zod';
+import { LocationTypeSchema } from './context.schemas.js';
+export { LocationTypeSchema };
+/**
+ * Validation error code values
+ *
+ * Mirrors CONTEXT_VALIDATION.ERROR_CODES from wu-constants.ts
+ */
+export declare const VALIDATION_ERROR_CODE_VALUES: readonly ["WRONG_LOCATION", "WU_NOT_FOUND", "WU_ALREADY_EXISTS", "WRONG_WU_STATUS", "LANE_OCCUPIED", "WORKTREE_EXISTS", "WORKTREE_MISSING", "GATES_NOT_PASSED", "DIRTY_GIT", "REMOTE_UNAVAILABLE", "INCONSISTENT_STATE"];
+/**
+ * Schema for validation error codes
+ */
+export declare const ValidationErrorCodeSchema: z.ZodEnum<{
+    WU_NOT_FOUND: "WU_NOT_FOUND";
+    WRONG_LOCATION: "WRONG_LOCATION";
+    WU_ALREADY_EXISTS: "WU_ALREADY_EXISTS";
+    WRONG_WU_STATUS: "WRONG_WU_STATUS";
+    LANE_OCCUPIED: "LANE_OCCUPIED";
+    WORKTREE_EXISTS: "WORKTREE_EXISTS";
+    WORKTREE_MISSING: "WORKTREE_MISSING";
+    GATES_NOT_PASSED: "GATES_NOT_PASSED";
+    DIRTY_GIT: "DIRTY_GIT";
+    REMOTE_UNAVAILABLE: "REMOTE_UNAVAILABLE";
+    INCONSISTENT_STATE: "INCONSISTENT_STATE";
+}>;
+/**
+ * Severity values
+ *
+ * Mirrors CONTEXT_VALIDATION.SEVERITY from wu-constants.ts
+ */
+export declare const PREDICATE_SEVERITY_VALUES: readonly ["error", "warning"];
+/**
+ * Schema for predicate severity
+ */
+export declare const PredicateSeveritySchema: z.ZodEnum<{
+    error: "error";
+    warning: "warning";
+}>;
+/**
+ * Schema for validation error with fix guidance
+ */
+export declare const ValidationErrorSchema: z.ZodObject<{
+    code: z.ZodEnum<{
+        WU_NOT_FOUND: "WU_NOT_FOUND";
+        WRONG_LOCATION: "WRONG_LOCATION";
+        WU_ALREADY_EXISTS: "WU_ALREADY_EXISTS";
+        WRONG_WU_STATUS: "WRONG_WU_STATUS";
+        LANE_OCCUPIED: "LANE_OCCUPIED";
+        WORKTREE_EXISTS: "WORKTREE_EXISTS";
+        WORKTREE_MISSING: "WORKTREE_MISSING";
+        GATES_NOT_PASSED: "GATES_NOT_PASSED";
+        DIRTY_GIT: "DIRTY_GIT";
+        REMOTE_UNAVAILABLE: "REMOTE_UNAVAILABLE";
+        INCONSISTENT_STATE: "INCONSISTENT_STATE";
+    }>;
+    message: z.ZodString;
+    fixCommand: z.ZodNullable<z.ZodString>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * Schema for validation warning (non-blocking)
+ */
+export declare const ValidationWarningSchema: z.ZodObject<{
+    id: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Schema for validation result (partial, without context for serialization)
+ *
+ * Note: The full ValidationResult in types.ts includes the context object,
+ * but this schema is for serializable results without the context.
+ */
+export declare const ValidationResultSchema: z.ZodObject<{
+    valid: z.ZodBoolean;
+    errors: z.ZodArray<z.ZodObject<{
+        code: z.ZodEnum<{
+            WU_NOT_FOUND: "WU_NOT_FOUND";
+            WRONG_LOCATION: "WRONG_LOCATION";
+            WU_ALREADY_EXISTS: "WU_ALREADY_EXISTS";
+            WRONG_WU_STATUS: "WRONG_WU_STATUS";
+            LANE_OCCUPIED: "LANE_OCCUPIED";
+            WORKTREE_EXISTS: "WORKTREE_EXISTS";
+            WORKTREE_MISSING: "WORKTREE_MISSING";
+            GATES_NOT_PASSED: "GATES_NOT_PASSED";
+            DIRTY_GIT: "DIRTY_GIT";
+            REMOTE_UNAVAILABLE: "REMOTE_UNAVAILABLE";
+            INCONSISTENT_STATE: "INCONSISTENT_STATE";
+        }>;
+        message: z.ZodString;
+        fixCommand: z.ZodNullable<z.ZodString>;
+        context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    warnings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Schema for command predicate configuration (serializable)
+ *
+ * This schema represents the serializable configuration of a predicate,
+ * not the full CommandPredicate which includes the check function.
+ */
+export declare const CommandPredicateConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+    }>;
+}, z.core.$strip>;
+/**
+ * Schema for command definition configuration (serializable)
+ *
+ * This schema represents the serializable configuration of a command definition,
+ * not the full CommandDefinition which includes function references.
+ */
+export declare const CommandDefinitionConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    requiredLocation: z.ZodNullable<z.ZodEnum<{
+        unknown: "unknown";
+        main: "main";
+        worktree: "worktree";
+        detached: "detached";
+    }>>;
+    requiredWuStatus: z.ZodNullable<z.ZodString>;
+    predicateIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ValidationErrorCode = z.infer<typeof ValidationErrorCodeSchema>;
+export type PredicateSeverity = z.infer<typeof PredicateSeveritySchema>;
+export type ValidationError = z.infer<typeof ValidationErrorSchema>;
+export type ValidationWarning = z.infer<typeof ValidationWarningSchema>;
+export type ValidationResult = z.infer<typeof ValidationResultSchema>;
+export type CommandPredicateConfig = z.infer<typeof CommandPredicateConfigSchema>;
+export type CommandDefinitionConfig = z.infer<typeof CommandDefinitionConfigSchema>;

package/dist/domain/validation.schemas.js

@@ -0,0 +1,114 @@
+/**
+ * Validation Schemas
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ *
+ * Zod schemas for validation-related types in the context-aware validation system.
+ * Types are inferred from Zod schemas using z.infer<> for single source of truth.
+ *
+ * @module domain/validation.schemas
+ */
+import { z } from 'zod';
+import { LocationTypeSchema } from './context.schemas.js';
+// Re-export LocationTypeSchema for command definitions
+export { LocationTypeSchema };
+/**
+ * Validation error code values
+ *
+ * Mirrors CONTEXT_VALIDATION.ERROR_CODES from wu-constants.ts
+ */
+export const VALIDATION_ERROR_CODE_VALUES = [
+    'WRONG_LOCATION',
+    'WU_NOT_FOUND',
+    'WU_ALREADY_EXISTS',
+    'WRONG_WU_STATUS',
+    'LANE_OCCUPIED',
+    'WORKTREE_EXISTS',
+    'WORKTREE_MISSING',
+    'GATES_NOT_PASSED',
+    'DIRTY_GIT',
+    'REMOTE_UNAVAILABLE',
+    'INCONSISTENT_STATE',
+];
+/**
+ * Schema for validation error codes
+ */
+export const ValidationErrorCodeSchema = z.enum(VALIDATION_ERROR_CODE_VALUES);
+/**
+ * Severity values
+ *
+ * Mirrors CONTEXT_VALIDATION.SEVERITY from wu-constants.ts
+ */
+export const PREDICATE_SEVERITY_VALUES = ['error', 'warning'];
+/**
+ * Schema for predicate severity
+ */
+export const PredicateSeveritySchema = z.enum(PREDICATE_SEVERITY_VALUES);
+/**
+ * Schema for validation error with fix guidance
+ */
+export const ValidationErrorSchema = z.object({
+    /** Error code */
+    code: ValidationErrorCodeSchema,
+    /** Human-readable message */
+    message: z.string(),
+    /** Copy-paste ready fix command (if available) */
+    fixCommand: z.string().nullable(),
+    /** Additional context for debugging */
+    context: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * Schema for validation warning (non-blocking)
+ */
+export const ValidationWarningSchema = z.object({
+    /** Warning ID */
+    id: z.string(),
+    /** Human-readable message */
+    message: z.string(),
+});
+/**
+ * Schema for validation result (partial, without context for serialization)
+ *
+ * Note: The full ValidationResult in types.ts includes the context object,
+ * but this schema is for serializable results without the context.
+ */
+export const ValidationResultSchema = z.object({
+    /** Whether command can proceed */
+    valid: z.boolean(),
+    /** Errors that block execution */
+    errors: z.array(ValidationErrorSchema),
+    /** Warnings that don't block execution */
+    warnings: z.array(ValidationWarningSchema),
+});
+/**
+ * Schema for command predicate configuration (serializable)
+ *
+ * This schema represents the serializable configuration of a predicate,
+ * not the full CommandPredicate which includes the check function.
+ */
+export const CommandPredicateConfigSchema = z.object({
+    /** Unique identifier for the predicate */
+    id: z.string(),
+    /** Human-readable description */
+    description: z.string(),
+    /** Severity: 'error' blocks execution, 'warning' allows with warning */
+    severity: PredicateSeveritySchema,
+});
+/**
+ * Schema for command definition configuration (serializable)
+ *
+ * This schema represents the serializable configuration of a command definition,
+ * not the full CommandDefinition which includes function references.
+ */
+export const CommandDefinitionConfigSchema = z.object({
+    /** Command name (e.g., 'wu:create') */
+    name: z.string(),
+    /** Human-readable description */
+    description: z.string(),
+    /** Required location type (null = any location) */
+    requiredLocation: LocationTypeSchema.nullable(),
+    /** Required WU status (null = no status requirement) */
+    requiredWuStatus: z.string().nullable(),
+    /** Predicate IDs for additional checks */
+    predicateIds: z.array(z.string()),
+});

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from './date-utils.js';
 export * from './error-handler.js';
 export * from './retry-strategy.js';
 export * from './beacon-migration.js';
+export * from './cycle-detector.js';
 export { DEFAULT_DOMAIN, inferDefaultDomain, normalizeToEmail, isValidEmail, } from './user-normalizer.js';
 export * from './git-adapter.js';
 export * from './state-machine.js';
@@ -47,3 +48,19 @@ export * from './agent-patterns-registry.js';
 export * from './lumenflow-home.js';
 export * from './force-bypass-audit.js';
 export { LUMENFLOW_PATHS, BEACON_PATHS } from './wu-constants.js';
+export * from './color-support.js';
+export * from './context/index.js';
+export * from './validation/index.js';
+export * from './recovery/index.js';
+export * from './context-validation-integration.js';
+export { CONTEXT_VALIDATION } from './wu-constants.js';
+export type { LocationType, ValidationErrorCode, RecoveryActionType, RecoveryIssueCode, PredicateSeverity, ValidationMode, } from './wu-constants.js';
+export type { ILocationResolver, IGitStateReader, IWuStateReader } from './ports/context.ports.js';
+export type { ICommandRegistry } from './ports/validation.ports.js';
+export type { IRecoveryAnalyzer } from './ports/recovery.ports.js';
+export { LOCATION_TYPE_VALUES, LocationTypeSchema, LocationContextSchema, GitStateSchema, WuStateResultSchema, SessionStateSchema, WuContextSchema, } from './domain/context.schemas.js';
+export { VALIDATION_ERROR_CODE_VALUES, ValidationErrorCodeSchema, PREDICATE_SEVERITY_VALUES, PredicateSeveritySchema, ValidationErrorSchema, ValidationWarningSchema, ValidationResultSchema, CommandPredicateConfigSchema, CommandDefinitionConfigSchema, type CommandPredicateConfig, type CommandDefinitionConfig, } from './domain/validation.schemas.js';
+export { RECOVERY_ISSUE_CODE_VALUES, RecoveryIssueCodeSchema, RECOVERY_ACTION_TYPE_VALUES, RecoveryActionTypeSchema, RecoveryIssueSchema, RecoveryActionSchema, RecoveryAnalysisSchema, } from './domain/recovery.schemas.js';
+export { SimpleGitLocationAdapter, SimpleGitStateAdapter, FileSystemWuStateAdapter, CommandRegistryAdapter, RecoveryAnalyzerAdapter, } from './adapters/index.js';
+export { ComputeContextUseCase, type ComputeContextOptions, ValidateCommandUseCase, AnalyzeRecoveryUseCase, } from './usecases/index.js';
+export { createContextAdapters, createValidationAdapters, createRecoveryAdapters, createComputeContextUseCase, createValidateCommandUseCase, createAnalyzeRecoveryUseCase, computeWuContext, validateCommand, analyzeRecoveryIssues, type ContextAdapters, type ValidationAdapters, type RecoveryAdapters, type CreateComputeContextOptions, type CreateValidateCommandOptions, type CreateAnalyzeRecoveryOptions, } from './context-di.js';

package/dist/index.js

@@ -11,6 +11,8 @@ export * from './error-handler.js';
 export * from './retry-strategy.js';
 // Migration utilities (WU-1075)
 export * from './beacon-migration.js';
+// Cycle detection (WU-1088 - extracted from initiatives to break circular dependency)
+export * from './cycle-detector.js';
 // User normalizer (explicit exports to avoid conflicts)
 export { DEFAULT_DOMAIN, inferDefaultDomain, normalizeToEmail, isValidEmail, } from './user-normalizer.js';
 // Git operations
@@ -73,3 +75,48 @@ export * from './lumenflow-home.js';
 export * from './force-bypass-audit.js';
 // WU-1075: LumenFlow directory paths (exported from wu-constants)
 export { LUMENFLOW_PATHS, BEACON_PATHS } from './wu-constants.js';
+// WU-1085: Color support for NO_COLOR/FORCE_COLOR/--no-color
+export * from './color-support.js';
+// WU-1090: Context-aware state machine for WU lifecycle commands
+export * from './context/index.js';
+export * from './validation/index.js';
+export * from './recovery/index.js';
+export * from './context-validation-integration.js';
+// WU-1090: Context validation constants
+export { CONTEXT_VALIDATION } from './wu-constants.js';
+// WU-1093: Domain schemas for context-aware validation (Zod schemas)
+// Note: Types like LocationContext, GitState are already exported from context/index.js
+// so we only export the Zod schemas, not the inferred types.
+export { 
+// Context schemas
+LOCATION_TYPE_VALUES, LocationTypeSchema, LocationContextSchema, GitStateSchema, WuStateResultSchema, SessionStateSchema, WuContextSchema, } from './domain/context.schemas.js';
+export { 
+// Validation schemas
+VALIDATION_ERROR_CODE_VALUES, ValidationErrorCodeSchema, PREDICATE_SEVERITY_VALUES, PredicateSeveritySchema, ValidationErrorSchema, ValidationWarningSchema, ValidationResultSchema, CommandPredicateConfigSchema, CommandDefinitionConfigSchema, } from './domain/validation.schemas.js';
+export { 
+// Recovery schemas
+RECOVERY_ISSUE_CODE_VALUES, RecoveryIssueCodeSchema, RECOVERY_ACTION_TYPE_VALUES, RecoveryActionTypeSchema, RecoveryIssueSchema, RecoveryActionSchema, RecoveryAnalysisSchema, } from './domain/recovery.schemas.js';
+// WU-1094: Adapters - Concrete implementations of port interfaces
+export { 
+// Context adapters
+SimpleGitLocationAdapter, SimpleGitStateAdapter, FileSystemWuStateAdapter, 
+// Validation adapters
+CommandRegistryAdapter, 
+// Recovery adapters
+RecoveryAnalyzerAdapter, } from './adapters/index.js';
+// WU-1094: Use Cases - Application layer business logic
+export { 
+// Context use cases
+ComputeContextUseCase, 
+// Validation use cases
+ValidateCommandUseCase, 
+// Recovery use cases
+AnalyzeRecoveryUseCase, } from './usecases/index.js';
+// WU-1094: Dependency Injection - Factory functions for wiring
+export { 
+// Adapter factory functions
+createContextAdapters, createValidationAdapters, createRecoveryAdapters, 
+// Use case factory functions
+createComputeContextUseCase, createValidateCommandUseCase, createAnalyzeRecoveryUseCase, 
+// Backwards compatible convenience functions
+computeWuContext, validateCommand, analyzeRecoveryIssues, } from './context-di.js';

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

@@ -53,6 +53,8 @@ export declare const GitConfigSchema: z.ZodObject<{
     branchDriftWarning: z.ZodDefault<z.ZodNumber>;
     branchDriftInfo: z.ZodDefault<z.ZodNumber>;
     agentBranchPatterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    agentBranchPatternsOverride: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    disableAgentPatternRegistry: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 /**
  * WU (Work Unit) configuration
@@ -203,6 +205,29 @@ export declare const AgentsConfigSchema: z.ZodObject<{
         notes: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * Validation mode for context-aware commands
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ */
+export declare const ValidationModeSchema: z.ZodDefault<z.ZodEnum<{
+    error: "error";
+    off: "off";
+    warn: "warn";
+}>>;
+/**
+ * Experimental features configuration
+ * WU-1090: Feature flags for gradual rollout
+ */
+export declare const ExperimentalConfigSchema: z.ZodObject<{
+    context_validation: z.ZodDefault<z.ZodBoolean>;
+    validation_mode: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        off: "off";
+        warn: "warn";
+    }>>;
+    show_next_steps: z.ZodDefault<z.ZodBoolean>;
+    recovery_command: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
 /**
  * Complete LumenFlow configuration schema
  */
@@ -245,6 +270,8 @@ export declare const LumenFlowConfigSchema: z.ZodObject<{
         branchDriftWarning: z.ZodDefault<z.ZodNumber>;
         branchDriftInfo: z.ZodDefault<z.ZodNumber>;
         agentBranchPatterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        agentBranchPatternsOverride: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        disableAgentPatternRegistry: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     wu: z.ZodDefault<z.ZodObject<{
         idPattern: z.ZodDefault<z.ZodString>;
@@ -331,6 +358,16 @@ export declare const LumenFlowConfigSchema: z.ZodObject<{
             notes: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    experimental: z.ZodDefault<z.ZodObject<{
+        context_validation: z.ZodDefault<z.ZodBoolean>;
+        validation_mode: z.ZodDefault<z.ZodEnum<{
+            error: "error";
+            off: "off";
+            warn: "warn";
+        }>>;
+        show_next_steps: z.ZodDefault<z.ZodBoolean>;
+        recovery_command: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
  * TypeScript types inferred from schemas
@@ -348,6 +385,8 @@ export type ClientBlock = z.infer<typeof ClientBlockSchema>;
 export type ClientSkills = z.infer<typeof ClientSkillsSchema>;
 export type ClientConfig = z.infer<typeof ClientConfigSchema>;
 export type AgentsConfig = z.infer<typeof AgentsConfigSchema>;
+export type ExperimentalConfig = z.infer<typeof ExperimentalConfigSchema>;
+export type ValidationMode = z.infer<typeof ValidationModeSchema>;
 export type LumenFlowConfig = z.infer<typeof LumenFlowConfigSchema>;
 /**
  * Validate configuration data
@@ -394,6 +433,8 @@ export declare function validateConfig(data: unknown): z.ZodSafeParseResult<{
         branchDriftWarning: number;
         branchDriftInfo: number;
         agentBranchPatterns: string[];
+        disableAgentPatternRegistry: boolean;
+        agentBranchPatternsOverride?: string[];
     };
     wu: {
         idPattern: string;
@@ -477,6 +518,12 @@ export declare function validateConfig(data: unknown): z.ZodSafeParseResult<{
             notes?: string;
         };
     };
+    experimental: {
+        context_validation: boolean;
+        validation_mode: "error" | "off" | "warn";
+        show_next_steps: boolean;
+        recovery_command: boolean;
+    };
 }>;
 /**
  * Parse configuration with defaults

package/dist/lumenflow-config-schema.js

@@ -86,12 +86,55 @@ export const GitConfigSchema = z.object({
     /** Info threshold for branch drift */
     branchDriftInfo: z.number().int().positive().default(10),
     /**
-     * Agent branch patterns that bypass worktree requirements.
-     * Branches matching these glob patterns can work in the main checkout.
-     * Default: ['agent/*'] - narrow default, add vendor patterns as needed.
+     * Agent branch patterns to MERGE with the registry patterns.
+     * These patterns are merged with patterns from lumenflow.dev/registry/agent-patterns.json.
+     * Use this to add custom patterns that should work alongside the standard vendor patterns.
      * Protected branches (mainBranch + 'master') are NEVER bypassed.
+     *
+     * WU-1089: Changed default from ['agent/*'] to [] to allow registry to be used by default.
+     *
+     * @example
+     * ```yaml
+     * git:
+     *   agentBranchPatterns:
+     *     - 'my-custom-agent/*'
+     *     - 'internal-tool/*'
+     * ```
      */
-    agentBranchPatterns: z.array(z.string()).default(['agent/*']),
+    agentBranchPatterns: z.array(z.string()).default([]),
+    /**
+     * Agent branch patterns that REPLACE the registry patterns entirely.
+     * When set, these patterns are used instead of fetching from the registry.
+     * The agentBranchPatterns field is ignored when this is set.
+     *
+     * Use this for strict control over which agent patterns are allowed.
+     *
+     * @example
+     * ```yaml
+     * git:
+     *   agentBranchPatternsOverride:
+     *     - 'claude/*'
+     *     - 'codex/*'
+     * ```
+     */
+    agentBranchPatternsOverride: z.array(z.string()).optional(),
+    /**
+     * Disable fetching agent patterns from the registry (airgapped mode).
+     * When true, only uses agentBranchPatterns from config or defaults to ['agent/*'].
+     * Useful for environments without network access or strict security requirements.
+     *
+     * @default false
+     *
+     * @example
+     * ```yaml
+     * git:
+     *   disableAgentPatternRegistry: true
+     *   agentBranchPatterns:
+     *     - 'claude/*'
+     *     - 'cursor/*'
+     * ```
+     */
+    disableAgentPatternRegistry: z.boolean().default(false),
 });
 /**
  * WU (Work Unit) configuration
@@ -238,6 +281,41 @@ export const AgentsConfigSchema = z.object({
     /** Project methodology defaults (agent-facing) */
     methodology: MethodologyDefaultsSchema.default(() => MethodologyDefaultsSchema.parse({})),
 });
+/**
+ * Validation mode for context-aware commands
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ */
+export const ValidationModeSchema = z.enum(['off', 'warn', 'error']).default('warn');
+/**
+ * Experimental features configuration
+ * WU-1090: Feature flags for gradual rollout
+ */
+export const ExperimentalConfigSchema = z.object({
+    /**
+     * Enable context-aware validation for wu:* commands
+     * When enabled, commands will check location, WU status, and predicates
+     * @default true
+     */
+    context_validation: z.boolean().default(true),
+    /**
+     * Validation behavior mode
+     * - 'off': No validation (legacy behavior)
+     * - 'warn': Show warnings but proceed
+     * - 'error': Block on validation failures
+     * @default 'warn'
+     */
+    validation_mode: ValidationModeSchema,
+    /**
+     * Show next steps guidance after successful command completion
+     * @default true
+     */
+    show_next_steps: z.boolean().default(true),
+    /**
+     * Enable wu:recover command for state recovery
+     * @default true
+     */
+    recovery_command: z.boolean().default(true),
+});
 /**
  * Complete LumenFlow configuration schema
  */
@@ -262,6 +340,8 @@ export const LumenFlowConfigSchema = z.object({
     yaml: YamlConfigSchema.default(() => YamlConfigSchema.parse({})),
     /** Agents configuration */
     agents: AgentsConfigSchema.default(() => AgentsConfigSchema.parse({})),
+    /** Experimental features (WU-1090) */
+    experimental: ExperimentalConfigSchema.default(() => ExperimentalConfigSchema.parse({})),
 });
 /**
  * Validate configuration data

package/dist/ports/context.ports.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Context Ports
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ *
+ * Port interfaces for context-aware validation system.
+ * These abstractions allow external users to inject custom implementations.
+ *
+ * Hexagonal Architecture - Input Ports:
+ * - ILocationResolver: Detect main checkout vs worktree
+ * - IGitStateReader: Read git branch, dirty state, ahead/behind
+ * - IWuStateReader: Read WU state from YAML and state store
+ *
+ * Current Implementations:
+ * - resolveLocation (location-resolver.ts)
+ * - readGitState (git-state-reader.ts)
+ * - readWuState (wu-state-reader.ts)
+ *
+ * @module ports/context
+ */
+import type { LocationContext } from '../context/location-resolver.js';
+import type { GitState } from '../context/git-state-reader.js';
+import type { WuStateResult } from '../context/wu-state-reader.js';
+/**
+ * Location Resolver Port Interface
+ *
+ * Resolves the current working directory context to determine:
+ * - Whether in main checkout or a worktree
+ * - Path to main checkout
+ * - Worktree name and associated WU ID (if applicable)
+ *
+ * @example
+ * // Custom implementation for testing
+ * const mockResolver: ILocationResolver = {
+ *   resolveLocation: async (cwd) => ({
+ *     type: 'main',
+ *     cwd: cwd || '/repo',
+ *     gitRoot: '/repo',
+ *     mainCheckout: '/repo',
+ *     worktreeName: null,
+ *     worktreeWuId: null,
+ *   }),
+ * };
+ *
+ * @example
+ * // Using default implementation
+ * import { resolveLocation } from './context/location-resolver.js';
+ * const resolver: ILocationResolver = { resolveLocation };
+ */
+export interface ILocationResolver {
+    /**
+     * Resolve location context for the given working directory.
+     *
+     * @param cwd - Current working directory (defaults to process.cwd())
+     * @returns Promise<LocationContext> - Resolved location context
+     */
+    resolveLocation(cwd?: string): Promise<LocationContext>;
+}
+/**
+ * Git State Reader Port Interface
+ *
+ * Reads the current git state including:
+ * - Current branch name
+ * - Whether HEAD is detached
+ * - Dirty working tree (uncommitted changes)
+ * - Staged changes
+ * - Commits ahead/behind tracking branch
+ *
+ * @example
+ * // Custom implementation for testing
+ * const mockReader: IGitStateReader = {
+ *   readGitState: async () => ({
+ *     branch: 'main',
+ *     isDetached: false,
+ *     isDirty: false,
+ *     hasStaged: false,
+ *     ahead: 0,
+ *     behind: 0,
+ *     tracking: 'origin/main',
+ *     modifiedFiles: [],
+ *     hasError: false,
+ *     errorMessage: null,
+ *   }),
+ * };
+ *
+ * @example
+ * // Using default implementation
+ * import { readGitState } from './context/git-state-reader.js';
+ * const reader: IGitStateReader = { readGitState };
+ */
+export interface IGitStateReader {
+    /**
+     * Read current git state for the given working directory.
+     *
+     * @param cwd - Current working directory (defaults to process.cwd())
+     * @returns Promise<GitState> - Current git state
+     */
+    readGitState(cwd?: string): Promise<GitState>;
+}
+/**
+ * WU State Reader Port Interface
+ *
+ * Reads WU state from YAML file and optionally cross-references
+ * with state store for inconsistency detection.
+ *
+ * @example
+ * // Custom implementation for testing
+ * const mockReader: IWuStateReader = {
+ *   readWuState: async (wuId, repoRoot) => ({
+ *     id: wuId,
+ *     status: 'in_progress',
+ *     lane: 'Framework: Core',
+ *     title: 'Test WU',
+ *     yamlPath: `${repoRoot}/docs/04-operations/tasks/wu/${wuId}.yaml`,
+ *     isConsistent: true,
+ *     inconsistencyReason: null,
+ *   }),
+ * };
+ *
+ * @example
+ * // Using default implementation
+ * import { readWuState } from './context/wu-state-reader.js';
+ * const reader: IWuStateReader = { readWuState };
+ */
+export interface IWuStateReader {
+    /**
+     * Read WU state from YAML and detect inconsistencies.
+     *
+     * @param wuId - WU ID (e.g., 'WU-1093' or 'wu-1093')
+     * @param repoRoot - Repository root path
+     * @returns Promise<WuStateResult | null> - WU state or null if not found
+     */
+    readWuState(wuId: string, repoRoot: string): Promise<WuStateResult | null>;
+}
+export type { LocationContext, GitState, WuStateResult };