@lumenflow/core 1.5.0 → 2.0.0

package/dist/wu-constants.d.ts

@@ -147,6 +147,14 @@ export declare const PATTERNS: {
     WU_ID: RegExp;
     /** Extract WU ID from text: captures "WU-123" */
     WU_ID_EXTRACT: RegExp;
+    /**
+     * Extract WU ID from worktree paths (case-insensitive)
+     *
+     * WU-1090: Worktree names use lowercase like 'framework-core-wu-1090'
+     * This pattern matches both 'WU-123' and 'wu-123' to support
+     * extracting WU IDs from worktree paths.
+     */
+    WU_ID_EXTRACT_CI: RegExp;
     /** Lane branch format: lane/<lane-kebab>/wu-<id> */
     LANE_BRANCH: RegExp;
     /** Worktree path format: worktrees/<lane-kebab>-wu-<id> */
@@ -1547,3 +1555,131 @@ export declare function validateSafetyTestsExist(options?: DiscoverSafetyTestsOp
     foundTests: any[];
     error: string;
 }>;
+/**
+ * Context validation constants (WU-1090)
+ *
+ * Constants for the context-aware state machine for WU lifecycle commands.
+ * Supports unified context model, declarative command requirements,
+ * smart validation, and recovery paths.
+ */
+export declare const CONTEXT_VALIDATION: {
+    /** Location types for WU operations */
+    readonly LOCATION_TYPES: {
+        /** Main checkout (not a worktree) */
+        readonly MAIN: "main";
+        /** Inside a worktree */
+        readonly WORKTREE: "worktree";
+        /** Detached HEAD state */
+        readonly DETACHED: "detached";
+        /** Unknown location (not a git repo or error) */
+        readonly UNKNOWN: "unknown";
+    };
+    /** Validation error codes */
+    readonly ERROR_CODES: {
+        /** Command run from wrong location type */
+        readonly WRONG_LOCATION: "WRONG_LOCATION";
+        /** Target WU does not exist */
+        readonly WU_NOT_FOUND: "WU_NOT_FOUND";
+        /** WU with this ID already exists */
+        readonly WU_ALREADY_EXISTS: "WU_ALREADY_EXISTS";
+        /** WU in unexpected status for command */
+        readonly WRONG_WU_STATUS: "WRONG_WU_STATUS";
+        /** Lane already has WU in progress */
+        readonly LANE_OCCUPIED: "LANE_OCCUPIED";
+        /** Worktree already exists for WU */
+        readonly WORKTREE_EXISTS: "WORKTREE_EXISTS";
+        /** Expected worktree not found */
+        readonly WORKTREE_MISSING: "WORKTREE_MISSING";
+        /** Gates haven't run or failed */
+        readonly GATES_NOT_PASSED: "GATES_NOT_PASSED";
+        /** Uncommitted changes exist */
+        readonly DIRTY_GIT: "DIRTY_GIT";
+        /** Cannot reach origin remote */
+        readonly REMOTE_UNAVAILABLE: "REMOTE_UNAVAILABLE";
+        /** YAML and state store disagree */
+        readonly INCONSISTENT_STATE: "INCONSISTENT_STATE";
+    };
+    /** Recovery action types */
+    readonly RECOVERY_ACTIONS: {
+        /** Reconcile state and continue working (preserves work) */
+        readonly RESUME: "resume";
+        /** Discard worktree, reset WU to ready */
+        readonly RESET: "reset";
+        /** Remove all artifacts completely (requires --force) */
+        readonly NUKE: "nuke";
+        /** Remove leftover worktree (for done WUs) */
+        readonly CLEANUP: "cleanup";
+    };
+    /** Recovery issue codes */
+    readonly RECOVERY_ISSUES: {
+        /** Worktree exists but WU status is "ready" */
+        readonly PARTIAL_CLAIM: "PARTIAL_CLAIM";
+        /** WU is "in_progress" but worktree does not exist */
+        readonly ORPHAN_CLAIM: "ORPHAN_CLAIM";
+        /** YAML status differs from state store */
+        readonly INCONSISTENT_STATE: "INCONSISTENT_STATE";
+        /** Branch exists but worktree does not */
+        readonly ORPHAN_BRANCH: "ORPHAN_BRANCH";
+        /** Lock file from different WU */
+        readonly STALE_LOCK: "STALE_LOCK";
+        /** WU is done but worktree was not cleaned up */
+        readonly LEFTOVER_WORKTREE: "LEFTOVER_WORKTREE";
+    };
+    /** Predicate severity levels */
+    readonly SEVERITY: {
+        /** Blocks command execution */
+        readonly ERROR: "error";
+        /** Shows warning but allows execution */
+        readonly WARNING: "warning";
+    };
+    /** Performance thresholds */
+    readonly THRESHOLDS: {
+        /** Max context computation time (ms) - acceptance criterion */
+        readonly CONTEXT_COMPUTATION_MS: 100;
+        /** Max stale lock age (hours) */
+        readonly STALE_LOCK_HOURS: 24;
+    };
+    /** Feature flag keys for .lumenflow.config.yaml */
+    readonly FEATURE_FLAGS: {
+        /** Enable context-aware validation */
+        readonly CONTEXT_VALIDATION: "context_validation";
+        /** Validation behavior: 'off' | 'warn' | 'error' */
+        readonly VALIDATION_MODE: "validation_mode";
+        /** Show next steps after successful commands */
+        readonly SHOW_NEXT_STEPS: "show_next_steps";
+        /** Enable wu:recover command */
+        readonly RECOVERY_COMMAND: "recovery_command";
+    };
+    /** Validation modes */
+    readonly VALIDATION_MODES: {
+        /** No validation (legacy behavior) */
+        readonly OFF: "off";
+        /** Show warnings but proceed */
+        readonly WARN: "warn";
+        /** Block on validation failures */
+        readonly ERROR: "error";
+    };
+    /** Command names for the registry */
+    readonly COMMANDS: {
+        readonly WU_CREATE: "wu:create";
+        readonly WU_CLAIM: "wu:claim";
+        readonly WU_DONE: "wu:done";
+        readonly WU_BLOCK: "wu:block";
+        readonly WU_UNBLOCK: "wu:unblock";
+        readonly WU_STATUS: "wu:status";
+        readonly WU_RECOVER: "wu:recover";
+        readonly GATES: "gates";
+    };
+};
+/** Type for location types */
+export type LocationType = (typeof CONTEXT_VALIDATION.LOCATION_TYPES)[keyof typeof CONTEXT_VALIDATION.LOCATION_TYPES];
+/** Type for validation error codes */
+export type ValidationErrorCode = (typeof CONTEXT_VALIDATION.ERROR_CODES)[keyof typeof CONTEXT_VALIDATION.ERROR_CODES];
+/** Type for recovery action types */
+export type RecoveryActionType = (typeof CONTEXT_VALIDATION.RECOVERY_ACTIONS)[keyof typeof CONTEXT_VALIDATION.RECOVERY_ACTIONS];
+/** Type for recovery issue codes */
+export type RecoveryIssueCode = (typeof CONTEXT_VALIDATION.RECOVERY_ISSUES)[keyof typeof CONTEXT_VALIDATION.RECOVERY_ISSUES];
+/** Type for predicate severity levels */
+export type PredicateSeverity = (typeof CONTEXT_VALIDATION.SEVERITY)[keyof typeof CONTEXT_VALIDATION.SEVERITY];
+/** Type for validation modes */
+export type ValidationMode = (typeof CONTEXT_VALIDATION.VALIDATION_MODES)[keyof typeof CONTEXT_VALIDATION.VALIDATION_MODES];

package/dist/wu-constants.js

@@ -162,6 +162,14 @@ export const PATTERNS = {
     WU_ID: /^WU-\d+$/,
     /** Extract WU ID from text: captures "WU-123" */
     WU_ID_EXTRACT: /WU-\d+/,
+    /**
+     * Extract WU ID from worktree paths (case-insensitive)
+     *
+     * WU-1090: Worktree names use lowercase like 'framework-core-wu-1090'
+     * This pattern matches both 'WU-123' and 'wu-123' to support
+     * extracting WU IDs from worktree paths.
+     */
+    WU_ID_EXTRACT_CI: /wu-\d+/i,
     /** Lane branch format: lane/<lane-kebab>/wu-<id> */
     LANE_BRANCH: /^lane\/[\w-]+\/wu-\d+$/,
     /** Worktree path format: worktrees/<lane-kebab>-wu-<id> */
@@ -1627,3 +1635,119 @@ export async function validateSafetyTestsExist(options = {}) {
         error: valid ? undefined : `Missing safety-critical tests: ${missingTests.join('; ')}`,
     };
 }
+/**
+ * Context validation constants (WU-1090)
+ *
+ * Constants for the context-aware state machine for WU lifecycle commands.
+ * Supports unified context model, declarative command requirements,
+ * smart validation, and recovery paths.
+ */
+export const CONTEXT_VALIDATION = {
+    /** Location types for WU operations */
+    LOCATION_TYPES: {
+        /** Main checkout (not a worktree) */
+        MAIN: 'main',
+        /** Inside a worktree */
+        WORKTREE: 'worktree',
+        /** Detached HEAD state */
+        DETACHED: 'detached',
+        /** Unknown location (not a git repo or error) */
+        UNKNOWN: 'unknown',
+    },
+    /** Validation error codes */
+    ERROR_CODES: {
+        /** Command run from wrong location type */
+        WRONG_LOCATION: 'WRONG_LOCATION',
+        /** Target WU does not exist */
+        WU_NOT_FOUND: 'WU_NOT_FOUND',
+        /** WU with this ID already exists */
+        WU_ALREADY_EXISTS: 'WU_ALREADY_EXISTS',
+        /** WU in unexpected status for command */
+        WRONG_WU_STATUS: 'WRONG_WU_STATUS',
+        /** Lane already has WU in progress */
+        LANE_OCCUPIED: 'LANE_OCCUPIED',
+        /** Worktree already exists for WU */
+        WORKTREE_EXISTS: 'WORKTREE_EXISTS',
+        /** Expected worktree not found */
+        WORKTREE_MISSING: 'WORKTREE_MISSING',
+        /** Gates haven't run or failed */
+        GATES_NOT_PASSED: 'GATES_NOT_PASSED',
+        /** Uncommitted changes exist */
+        DIRTY_GIT: 'DIRTY_GIT',
+        /** Cannot reach origin remote */
+        REMOTE_UNAVAILABLE: 'REMOTE_UNAVAILABLE',
+        /** YAML and state store disagree */
+        INCONSISTENT_STATE: 'INCONSISTENT_STATE',
+    },
+    /** Recovery action types */
+    RECOVERY_ACTIONS: {
+        /** Reconcile state and continue working (preserves work) */
+        RESUME: 'resume',
+        /** Discard worktree, reset WU to ready */
+        RESET: 'reset',
+        /** Remove all artifacts completely (requires --force) */
+        NUKE: 'nuke',
+        /** Remove leftover worktree (for done WUs) */
+        CLEANUP: 'cleanup',
+    },
+    /** Recovery issue codes */
+    RECOVERY_ISSUES: {
+        /** Worktree exists but WU status is "ready" */
+        PARTIAL_CLAIM: 'PARTIAL_CLAIM',
+        /** WU is "in_progress" but worktree does not exist */
+        ORPHAN_CLAIM: 'ORPHAN_CLAIM',
+        /** YAML status differs from state store */
+        INCONSISTENT_STATE: 'INCONSISTENT_STATE',
+        /** Branch exists but worktree does not */
+        ORPHAN_BRANCH: 'ORPHAN_BRANCH',
+        /** Lock file from different WU */
+        STALE_LOCK: 'STALE_LOCK',
+        /** WU is done but worktree was not cleaned up */
+        LEFTOVER_WORKTREE: 'LEFTOVER_WORKTREE',
+    },
+    /** Predicate severity levels */
+    SEVERITY: {
+        /** Blocks command execution */
+        ERROR: 'error',
+        /** Shows warning but allows execution */
+        WARNING: 'warning',
+    },
+    /** Performance thresholds */
+    THRESHOLDS: {
+        /** Max context computation time (ms) - acceptance criterion */
+        CONTEXT_COMPUTATION_MS: 100,
+        /** Max stale lock age (hours) */
+        STALE_LOCK_HOURS: 24,
+    },
+    /** Feature flag keys for .lumenflow.config.yaml */
+    FEATURE_FLAGS: {
+        /** Enable context-aware validation */
+        CONTEXT_VALIDATION: 'context_validation',
+        /** Validation behavior: 'off' | 'warn' | 'error' */
+        VALIDATION_MODE: 'validation_mode',
+        /** Show next steps after successful commands */
+        SHOW_NEXT_STEPS: 'show_next_steps',
+        /** Enable wu:recover command */
+        RECOVERY_COMMAND: 'recovery_command',
+    },
+    /** Validation modes */
+    VALIDATION_MODES: {
+        /** No validation (legacy behavior) */
+        OFF: 'off',
+        /** Show warnings but proceed */
+        WARN: 'warn',
+        /** Block on validation failures */
+        ERROR: 'error',
+    },
+    /** Command names for the registry */
+    COMMANDS: {
+        WU_CREATE: 'wu:create',
+        WU_CLAIM: 'wu:claim',
+        WU_DONE: 'wu:done',
+        WU_BLOCK: 'wu:block',
+        WU_UNBLOCK: 'wu:unblock',
+        WU_STATUS: 'wu:status',
+        WU_RECOVER: 'wu:recover',
+        GATES: 'gates',
+    },
+};

package/dist/wu-helpers.d.ts

@@ -112,8 +112,12 @@ export declare function extractWUFromCommitMessage(message: any): any;
  * Centralized from duplicated ensureOnMain() functions across wu-* scripts (WU-1256).
  * Async version - accepts a git adapter with async getCurrentBranch() method.
  *
+ * WU-1091: Agent branches (claude/*, codex/*, copilot/*, cursor/*, agent/*) bypass
+ * the main branch requirement for web agent commands. Lane branches still require
+ * worktree workflow (no bypass). Protected branches (main/master) remain protected.
+ *
  * @param {object} git - Git adapter with async getCurrentBranch() method
- * @throws {Error} If not on main branch
+ * @throws {Error} If not on main branch and not an agent branch
  */
 export declare function ensureOnMain(git: any): Promise<void>;
 /**

package/dist/wu-helpers.js

@@ -13,6 +13,7 @@ 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';
+import { isAgentBranchWithDetails } from './branch-check.js';
 /**
  * Validate WU ID format
  *
@@ -220,12 +221,22 @@ export function extractWUFromCommitMessage(message) {
  * Centralized from duplicated ensureOnMain() functions across wu-* scripts (WU-1256).
  * Async version - accepts a git adapter with async getCurrentBranch() method.
  *
+ * WU-1091: Agent branches (claude/*, codex/*, copilot/*, cursor/*, agent/*) bypass
+ * the main branch requirement for web agent commands. Lane branches still require
+ * worktree workflow (no bypass). Protected branches (main/master) remain protected.
+ *
  * @param {object} git - Git adapter with async getCurrentBranch() method
- * @throws {Error} If not on main branch
+ * @throws {Error} If not on main branch and not an agent branch
  */
 export async function ensureOnMain(git) {
     const branch = await git.getCurrentBranch();
     if (branch !== BRANCHES.MAIN) {
+        // WU-1091: Check if this is an agent branch that can bypass the main requirement
+        const agentResult = await isAgentBranchWithDetails(branch);
+        if (agentResult.isMatch) {
+            console.log(`[ensureOnMain] Bypassing for agent branch '${branch}' (${agentResult.patternResult.source})`);
+            return;
+        }
         throw new Error(`Run from shared checkout on '${BRANCHES.MAIN}' (found '${branch}')`);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/core",
-  "version": "1.5.0",
+  "version": "2.0.0",
   "description": "Core WU lifecycle tools for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -78,7 +78,9 @@
     "micromatch": "^4.0.8",
     "minimatch": "^10.1.1",
     "ms": "^2.1.3",
+    "nhs-number-validator": "^1.1.2",
     "picocolors": "^1.1.1",
+    "postcode": "^5.1.0",
     "pretty-ms": "^9.2.0",
     "ps-list": "^8.1.1",
     "simple-git": "^3.30.0",
@@ -92,7 +94,7 @@
     "vitest": "^4.0.17"
   },
   "peerDependencies": {
-    "@lumenflow/memory": "1.5.0"
+    "@lumenflow/memory": "2.0.0"
   },
   "peerDependenciesMeta": {
     "@lumenflow/memory": {