@lumenflow/core 1.6.0 → 2.1.0

package/dist/index.d.ts

@@ -58,6 +58,8 @@ export type { LocationType, ValidationErrorCode, RecoveryActionType, RecoveryIss
 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 type { IWuGitAdapter, IWuStatusCheckResult, IBranchValidationResult, IWuYamlReader, IWuYamlWriter, IWuStateStore, IWuCheckpointManager, IWuPaths, } from './ports/wu-helpers.ports.js';
+export type { IGitAdapter, IPhiScanner, PHIMatch, PHIScanResult, PHIScanOptions, MergeOptions, MergeResult, PushOptions, DeleteBranchOptions, WorktreeRemoveOptions, } from './ports/git-validator.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';

package/dist/ports/core-tools.ports.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Core Tools Ports
+ *
+ * WU-1101: INIT-003 Phase 2a - Migrate tools/lib/core/ to @lumenflow/core
+ *
+ * Port interfaces for core tool modules migrated from PatientPath tools/lib/core/.
+ * These abstractions allow external users to inject custom implementations.
+ *
+ * Hexagonal Architecture - Input Ports:
+ * - IToolRunner: Execute tools with validation and guards
+ * - IWorktreeGuard: Detect and enforce worktree context
+ * - IScopeChecker: Validate file paths against WU code_paths
+ *
+ * Current Implementations:
+ * - runTool, ToolRunner (tool-runner.ts)
+ * - getWUContext, assertWorktreeRequired, isInWorktree, isMainBranch (worktree-guard.ts)
+ * - getActiveScope, isPathInScope, assertPathInScope (scope-checker.ts)
+ *
+ * @module ports/core-tools
+ */
+import type { ZodType } from 'zod';
+import type { ToolOutput, ToolError } from '../core/tool.schemas.js';
+import type { PermissionLevel, ToolDomain } from '../core/tool.constants.js';
+/**
+ * Tool metadata interface
+ */
+export interface IToolMetadata {
+    /** Tool name (unique identifier) */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Tool domain classification */
+    domain?: ToolDomain;
+    /** Required permission level */
+    permission: PermissionLevel;
+    /** Tool version */
+    version?: string;
+}
+/**
+ * Tool definition interface
+ */
+export interface IToolDefinition {
+    /** Tool metadata */
+    metadata: IToolMetadata;
+    /** Zod schema for input validation */
+    inputSchema?: ZodType;
+    /** Zod schema for output validation */
+    outputSchema?: ZodType;
+    /** Tool execution function */
+    execute: (input: unknown, context?: unknown) => Promise<ToolOutput>;
+}
+/**
+ * Tool configuration options
+ */
+export interface IToolConfigOptions {
+    /** Require worktree context for execution */
+    requiresWorktree?: boolean;
+    /** Require scope validation for file paths */
+    requiresScope?: boolean;
+    /** Enable audit logging */
+    enableAuditLog?: boolean;
+    /** Execution timeout in milliseconds */
+    timeoutMs?: number;
+}
+/**
+ * Tool execution options
+ */
+export interface IRunToolOptions {
+    /** Injected dependencies (for testing) */
+    dependencies?: Record<string, unknown>;
+    /** Configuration overrides */
+    config?: IToolConfigOptions;
+    /** Execution context (sessionId, userId, etc.) */
+    context?: Record<string, unknown>;
+}
+/**
+ * Tool Runner Port Interface
+ *
+ * Provides unified tool execution with validation, guards, and audit logging.
+ * Integrates worktree context detection and scope validation.
+ *
+ * @example
+ * // Direct tool execution
+ * const result = await runner.runTool(toolDefinition, { message: 'hello' });
+ *
+ * @example
+ * // Registry-based execution
+ * runner.register(myTool);
+ * const result = await runner.run('tool:name', { arg: 'value' });
+ */
+export interface IToolRunner {
+    /**
+     * Execute a tool with full validation and guards.
+     *
+     * @param tool - Tool definition
+     * @param input - Tool input arguments
+     * @param options - Execution options
+     * @returns Tool output (success/failure with data/error)
+     */
+    runTool(tool: IToolDefinition, input: unknown, options?: IRunToolOptions): Promise<ToolOutput>;
+    /**
+     * Register a tool definition.
+     *
+     * @param tool - Tool definition
+     * @throws Error if tool with same name already registered
+     */
+    register(tool: IToolDefinition): void;
+    /**
+     * Check if a tool is registered.
+     *
+     * @param name - Tool name
+     * @returns True if tool exists
+     */
+    hasTool(name: string): boolean;
+    /**
+     * Run a registered tool by name.
+     *
+     * @param name - Tool name
+     * @param input - Tool input
+     * @param options - Execution options
+     * @returns Tool output
+     */
+    run(name: string, input: unknown, options?: IRunToolOptions): Promise<ToolOutput>;
+    /**
+     * List all registered tools.
+     *
+     * @param options - Filter options
+     * @returns Array of tool metadata
+     */
+    listTools(options?: {
+        domain?: string;
+    }): IToolMetadata[];
+}
+/**
+ * WU context from worktree detection
+ */
+export interface IWUContext {
+    /** WU identifier (e.g., 'WU-1101') */
+    wuId: string;
+    /** Lane name in kebab-case (e.g., 'framework-core') */
+    lane: string;
+    /** Worktree path relative to repo root, or null if on lane branch */
+    worktreePath: string | null;
+}
+/**
+ * Worktree detection options
+ */
+export interface IWorktreeOptions {
+    /** Current working directory (defaults to process.cwd()) */
+    cwd?: string;
+    /** Git adapter instance (for testing) */
+    git?: {
+        getCurrentBranch(): Promise<string>;
+    };
+    /** Operation name for error messages */
+    operation?: string;
+}
+/**
+ * Worktree Guard Port Interface
+ *
+ * Provides runtime guards to enforce worktree discipline:
+ * - Detect if current directory is inside a worktree
+ * - Extract WU ID and lane from worktree path or git branch
+ * - Block write operations when not in worktree
+ *
+ * @example
+ * // Check worktree context
+ * const context = await guard.getWUContext();
+ * if (context) {
+ *   console.log(`Working on ${context.wuId} in ${context.lane}`);
+ * }
+ *
+ * @example
+ * // Assert worktree for write operation
+ * await guard.assertWorktreeRequired({ operation: 'file:write' });
+ */
+export interface IWorktreeGuard {
+    /**
+     * Check if current directory is inside a worktree.
+     *
+     * @param options - Detection options
+     * @returns True if inside a worktree directory
+     */
+    isInWorktree(options?: IWorktreeOptions): boolean;
+    /**
+     * Check if on main or master branch.
+     *
+     * @param options - Detection options
+     * @returns True if on main/master branch
+     */
+    isMainBranch(options?: IWorktreeOptions): Promise<boolean>;
+    /**
+     * Get WU context from worktree path or git branch.
+     *
+     * @param options - Detection options
+     * @returns WU context or null if not in WU workspace
+     */
+    getWUContext(options?: IWorktreeOptions): Promise<IWUContext | null>;
+    /**
+     * Assert that current context is inside a worktree or on a lane branch.
+     * Throws if on main branch in main checkout.
+     *
+     * @param options - Detection options
+     * @throws Error if not in worktree and on main branch
+     */
+    assertWorktreeRequired(options?: IWorktreeOptions): Promise<void>;
+}
+/**
+ * WU scope with code paths
+ */
+export interface IWUScope {
+    /** WU identifier */
+    wuId: string;
+    /** Allowed file paths/glob patterns */
+    code_paths: string[];
+}
+/**
+ * Scope Checker Port Interface
+ *
+ * Provides runtime validation that file modifications stay within WU code_paths.
+ * Prevents scope creep and ensures agents only modify authorized files.
+ *
+ * @example
+ * // Check if path is in scope
+ * const scope = await checker.getActiveScope();
+ * if (checker.isPathInScope('src/file.ts', scope)) {
+ *   // Safe to modify
+ * }
+ *
+ * @example
+ * // Assert path is in scope (throws if not)
+ * await checker.assertPathInScope('src/file.ts', scope, 'file:write');
+ */
+export interface IScopeChecker {
+    /**
+     * Get active WU scope (WU ID + code_paths).
+     *
+     * @param options - Options for dependency injection
+     * @returns Scope object or null if not in WU workspace
+     */
+    getActiveScope(options?: {
+        getWUContext?: () => Promise<IWUContext | null>;
+        loadWUYaml?: (wuId: string) => {
+            code_paths?: string[];
+        };
+    }): Promise<IWUScope | null>;
+    /**
+     * Check if a file path is within WU scope.
+     *
+     * @param filePath - File path to check
+     * @param scope - Scope object from getActiveScope()
+     * @returns True if path is in scope
+     */
+    isPathInScope(filePath: string, scope: IWUScope | null): boolean;
+    /**
+     * Assert that a file path is within WU scope.
+     * Throws if path is outside scope or no scope available.
+     *
+     * @param filePath - File path to check
+     * @param scope - Scope object from getActiveScope()
+     * @param operation - Operation name for error message
+     * @throws Error if path is outside scope
+     */
+    assertPathInScope(filePath: string, scope: IWUScope | null, operation?: string): void;
+}
+export type { ToolOutput, ToolError };

package/dist/ports/core-tools.ports.js

@@ -0,0 +1,21 @@
+/**
+ * Core Tools Ports
+ *
+ * WU-1101: INIT-003 Phase 2a - Migrate tools/lib/core/ to @lumenflow/core
+ *
+ * Port interfaces for core tool modules migrated from PatientPath tools/lib/core/.
+ * These abstractions allow external users to inject custom implementations.
+ *
+ * Hexagonal Architecture - Input Ports:
+ * - IToolRunner: Execute tools with validation and guards
+ * - IWorktreeGuard: Detect and enforce worktree context
+ * - IScopeChecker: Validate file paths against WU code_paths
+ *
+ * Current Implementations:
+ * - runTool, ToolRunner (tool-runner.ts)
+ * - getWUContext, assertWorktreeRequired, isInWorktree, isMainBranch (worktree-guard.ts)
+ * - getActiveScope, isPathInScope, assertPathInScope (scope-checker.ts)
+ *
+ * @module ports/core-tools
+ */
+export {};

package/dist/ports/git-validator.ports.d.ts

@@ -0,0 +1,314 @@
+/**
+ * Git Adapter and Validator Port Interfaces
+ *
+ * WU-1103: INIT-003 Phase 2c - Migrate git & validator modules
+ *
+ * Hexagonal Architecture - Input Ports:
+ * These abstractions allow external users to inject custom implementations
+ * for git operations and PHI scanning.
+ *
+ * @module ports/git-validator
+ */
+/**
+ * Merge options for git merge operations
+ */
+export interface MergeOptions {
+    /** Fast-forward only merge (--ff-only flag) */
+    ffOnly?: boolean;
+}
+/**
+ * Merge result from git merge operations
+ */
+export interface MergeResult {
+    /** Whether the merge succeeded */
+    success: boolean;
+}
+/**
+ * Push options for git push operations
+ */
+export interface PushOptions {
+    /** Set upstream tracking (-u flag) */
+    setUpstream?: boolean;
+}
+/**
+ * Delete branch options
+ */
+export interface DeleteBranchOptions {
+    /** Force delete (use -D instead of -d) */
+    force?: boolean;
+}
+/**
+ * Worktree remove options
+ */
+export interface WorktreeRemoveOptions {
+    /** Force removal */
+    force?: boolean;
+}
+/**
+ * Git Adapter Port Interface
+ *
+ * Abstracts git operations to allow dependency injection and testing.
+ * The default implementation uses simple-git library.
+ *
+ * @example
+ * // Custom implementation for testing
+ * const mockGit: IGitAdapter = {
+ *   getCurrentBranch: vi.fn().mockResolvedValue('main'),
+ *   getStatus: vi.fn().mockResolvedValue(''),
+ *   // ... other methods
+ * };
+ *
+ * @example
+ * // Using default implementation
+ * import { GitAdapter } from './git-adapter.js';
+ * const adapter: IGitAdapter = new GitAdapter({ baseDir: '/path' });
+ */
+export interface IGitAdapter {
+    /**
+     * Get current branch name
+     * @returns Promise resolving to branch name
+     * @example
+     * await git.getCurrentBranch(); // "lane/operations/wu-1213"
+     */
+    getCurrentBranch(): Promise<string>;
+    /**
+     * Get git status (porcelain format string)
+     * @returns Promise resolving to status output in porcelain format
+     * @example
+     * await git.getStatus(); // " M file.txt\n?? untracked.txt"
+     */
+    getStatus(): Promise<string>;
+    /**
+     * Check if a branch exists
+     * @param branch - Branch name to check
+     * @returns Promise resolving to true if branch exists
+     * @example
+     * await git.branchExists('main'); // true
+     */
+    branchExists(branch: string): Promise<boolean>;
+    /**
+     * Check if a remote branch exists
+     * @param remote - Remote name (e.g., 'origin')
+     * @param branch - Branch name
+     * @returns Promise resolving to true if remote branch exists
+     * @example
+     * await git.remoteBranchExists('origin', 'feature'); // true/false
+     */
+    remoteBranchExists(remote: string, branch: string): Promise<boolean>;
+    /**
+     * Check if working tree is clean (no uncommitted changes)
+     * @returns Promise resolving to true if clean
+     * @example
+     * await git.isClean(); // true or false
+     */
+    isClean(): Promise<boolean>;
+    /**
+     * Fetch from remote
+     * @param remote - Remote name (optional, defaults to fetching all)
+     * @param branch - Branch name (optional)
+     * @example
+     * await git.fetch('origin', 'main');
+     * await git.fetch(); // Fetch all remotes
+     */
+    fetch(remote?: string, branch?: string): Promise<void>;
+    /**
+     * Pull from remote branch
+     * @param remote - Remote name
+     * @param branch - Branch name
+     * @example
+     * await git.pull('origin', 'main');
+     */
+    pull(remote: string, branch: string): Promise<void>;
+    /**
+     * Add files to staging area
+     * @param files - Files to add (single file or array)
+     * @example
+     * await git.add('file.txt');
+     * await git.add(['file1.txt', 'file2.txt']);
+     */
+    add(files: string | string[]): Promise<void>;
+    /**
+     * Commit changes
+     * @param message - Commit message
+     * @example
+     * await git.commit('feat: add new feature');
+     */
+    commit(message: string): Promise<void>;
+    /**
+     * Push to remote
+     * @param remote - Remote name (defaults to 'origin')
+     * @param branch - Branch name (optional, uses current branch if not specified)
+     * @param options - Push options
+     * @example
+     * await git.push('origin', 'main');
+     * await git.push('origin', 'feature', { setUpstream: true });
+     */
+    push(remote?: string, branch?: string, options?: PushOptions): Promise<void>;
+    /**
+     * Checkout a branch
+     * @param branch - Branch name
+     * @example
+     * await git.checkout('main');
+     */
+    checkout(branch: string): Promise<void>;
+    /**
+     * Create and checkout a new branch
+     * @param branch - Branch name
+     * @param startPoint - Starting commit (optional, defaults to HEAD)
+     * @example
+     * await git.createBranch('feature/new-feature');
+     * await git.createBranch('hotfix/bug', 'main');
+     */
+    createBranch(branch: string, startPoint?: string): Promise<void>;
+    /**
+     * Delete a branch
+     * @param branch - Branch name
+     * @param options - Delete options
+     * @example
+     * await git.deleteBranch('feature');
+     * await git.deleteBranch('feature', { force: true });
+     */
+    deleteBranch(branch: string, options?: DeleteBranchOptions): Promise<void>;
+    /**
+     * Merge a branch
+     * @param branch - Branch to merge
+     * @param options - Merge options
+     * @returns Promise resolving to merge result
+     * @example
+     * await git.merge('feature-branch');
+     * await git.merge('feature-branch', { ffOnly: true });
+     */
+    merge(branch: string, options?: MergeOptions): Promise<MergeResult>;
+    /**
+     * Get commit hash
+     * @param ref - Git ref (optional, defaults to 'HEAD')
+     * @returns Promise resolving to commit hash
+     * @example
+     * await git.getCommitHash(); // "a1b2c3d..."
+     * await git.getCommitHash('main'); // "e4f5g6h..."
+     */
+    getCommitHash(ref?: string): Promise<string>;
+    /**
+     * Add a worktree with new branch
+     * @param path - Worktree path
+     * @param branch - Branch name
+     * @param startPoint - Starting commit (optional, defaults to HEAD)
+     * @example
+     * await git.worktreeAdd('worktrees/feature', 'feature-branch', 'main');
+     */
+    worktreeAdd(path: string, branch: string, startPoint?: string): Promise<void>;
+    /**
+     * Remove a worktree
+     * @param worktreePath - Worktree path
+     * @param options - Remove options
+     * @example
+     * await git.worktreeRemove('worktrees/feature');
+     * await git.worktreeRemove('worktrees/feature', { force: true });
+     */
+    worktreeRemove(worktreePath: string, options?: WorktreeRemoveOptions): Promise<void>;
+    /**
+     * List all worktrees
+     * @returns Promise resolving to worktree list in porcelain format
+     * @example
+     * await git.worktreeList();
+     */
+    worktreeList(): Promise<string>;
+    /**
+     * Execute arbitrary git command via raw()
+     * @param args - Git command arguments
+     * @returns Promise resolving to command output
+     * @example
+     * await git.raw(['status', '--porcelain']);
+     */
+    raw(args: string[]): Promise<string>;
+}
+/**
+ * PHI (Protected Health Information) match result
+ */
+export interface PHIMatch {
+    /** PHI type identifier (e.g., 'NHS_NUMBER', 'POSTCODE_MEDICAL_CONTEXT') */
+    type: string;
+    /** The matched value */
+    value: string;
+    /** Start position in content */
+    startIndex: number;
+    /** End position in content */
+    endIndex: number;
+    /** Medical keyword that triggered postcode detection (optional) */
+    medicalKeyword?: string;
+}
+/**
+ * PHI scan result
+ */
+export interface PHIScanResult {
+    /** Whether PHI was detected */
+    hasPHI: boolean;
+    /** Array of PHI matches found */
+    matches: PHIMatch[];
+    /** Non-blocking warnings (e.g., test data detected) */
+    warnings: string[];
+}
+/**
+ * Options for PHI scanning
+ */
+export interface PHIScanOptions {
+    /** File path for exclusion check */
+    filePath?: string;
+}
+/**
+ * PHI Scanner Port Interface
+ *
+ * Abstracts PHI (Protected Health Information) detection to allow
+ * dependency injection and testing. Detects NHS numbers and UK
+ * postcodes in medical context.
+ *
+ * @example
+ * // Custom implementation for testing
+ * const mockScanner: IPhiScanner = {
+ *   scanForPHI: vi.fn().mockReturnValue({ hasPHI: false, matches: [], warnings: [] }),
+ *   isPathExcluded: vi.fn().mockReturnValue(false),
+ *   formatPHISummary: vi.fn().mockReturnValue('No PHI detected'),
+ * };
+ *
+ * @example
+ * // Using default implementation
+ * import { scanForPHI, isPathExcluded, formatPHISummary } from './validators/phi-scanner.js';
+ * const scanner: IPhiScanner = { scanForPHI, isPathExcluded, formatPHISummary };
+ */
+export interface IPhiScanner {
+    /**
+     * Scan content for PHI (Protected Health Information)
+     *
+     * Detects:
+     * - Valid NHS numbers (validated with Modulus 11 checksum)
+     * - UK postcodes in medical context
+     *
+     * @param content - Content to scan
+     * @param options - Scan options
+     * @returns Scan result with matches and warnings
+     * @example
+     * scanner.scanForPHI('Patient NHS: 2983396339'); // { hasPHI: true, matches: [...], warnings: [] }
+     */
+    scanForPHI(content: string, options?: PHIScanOptions): PHIScanResult;
+    /**
+     * Check if a file path should be excluded from PHI scanning
+     *
+     * Test files, fixtures, mocks, and documentation are typically excluded.
+     *
+     * @param filePath - Path to check
+     * @returns True if path should be excluded
+     * @example
+     * scanner.isPathExcluded('src/__tests__/file.test.ts'); // true
+     * scanner.isPathExcluded('src/utils/helper.ts'); // false
+     */
+    isPathExcluded(filePath: string | null | undefined): boolean;
+    /**
+     * Create a human-readable summary of PHI matches
+     *
+     * @param matches - PHI matches from scanForPHI
+     * @returns Summary message
+     * @example
+     * scanner.formatPHISummary([{ type: 'NHS_NUMBER', ... }]); // "PHI detected: 1 NHS number"
+     */
+    formatPHISummary(matches: PHIMatch[]): string;
+}

package/dist/ports/git-validator.ports.js

@@ -0,0 +1,12 @@
+/**
+ * Git Adapter and Validator Port Interfaces
+ *
+ * WU-1103: INIT-003 Phase 2c - Migrate git & validator modules
+ *
+ * Hexagonal Architecture - Input Ports:
+ * These abstractions allow external users to inject custom implementations
+ * for git operations and PHI scanning.
+ *
+ * @module ports/git-validator
+ */
+export {};

package/dist/ports/index.d.ts

@@ -2,8 +2,11 @@
  * Ports Index
  *
  * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ * WU-1101: INIT-003 Phase 2a - Add core tools ports
+ * WU-1103: INIT-003 Phase 2c - Add git adapter and validator ports
  *
- * Re-exports all port interfaces for the context-aware validation system.
+ * Re-exports all port interfaces for the context-aware validation system
+ * and core tools (tool-runner, worktree-guard, scope-checker).
  *
  * @module ports
  */
@@ -12,3 +15,6 @@ export * from './validation.ports.js';
 export * from './recovery.ports.js';
 export * from './metrics-collector.port.js';
 export * from './dashboard-renderer.port.js';
+export * from './core-tools.ports.js';
+export * from './wu-helpers.ports.js';
+export * from './git-validator.ports.js';

package/dist/ports/index.js

@@ -2,8 +2,11 @@
  * Ports Index
  *
  * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ * WU-1101: INIT-003 Phase 2a - Add core tools ports
+ * WU-1103: INIT-003 Phase 2c - Add git adapter and validator ports
  *
- * Re-exports all port interfaces for the context-aware validation system.
+ * Re-exports all port interfaces for the context-aware validation system
+ * and core tools (tool-runner, worktree-guard, scope-checker).
  *
  * @module ports
  */
@@ -12,3 +15,6 @@ export * from './validation.ports.js';
 export * from './recovery.ports.js';
 export * from './metrics-collector.port.js';
 export * from './dashboard-renderer.port.js';
+export * from './core-tools.ports.js';
+export * from './wu-helpers.ports.js';
+export * from './git-validator.ports.js';

package/dist/ports/wu-helpers.ports.d.ts

@@ -0,0 +1,224 @@
+/**
+ * WU Helpers Port Interfaces
+ *
+ * WU-1102: INIT-003 Phase 2b - Port interfaces for WU helper modules
+ *
+ * Hexagonal Architecture - Input Ports:
+ * These abstractions allow external users to inject custom implementations
+ * for WU lifecycle operations.
+ *
+ * @module ports/wu-helpers
+ */
+/**
+ * Git adapter interface for ensureOnMain and ensureMainUpToDate operations
+ */
+export interface IWuGitAdapter {
+    /**
+     * Get the current git branch name
+     * @returns Promise resolving to branch name
+     */
+    getCurrentBranch(): Promise<string>;
+    /**
+     * Fetch from a remote
+     * @param remote - Remote name (e.g., 'origin')
+     * @param branch - Branch name (e.g., 'main')
+     */
+    fetch(remote: string, branch: string): Promise<void>;
+    /**
+     * Get commit hash for a ref
+     * @param ref - Git ref (branch, tag, or commit)
+     * @returns Promise resolving to commit hash
+     */
+    getCommitHash(ref: string): Promise<string>;
+}
+/**
+ * WU status check result
+ */
+export interface IWuStatusCheckResult {
+    /** Whether the operation is allowed */
+    allowed: boolean;
+    /** Current WU status */
+    status: string | null;
+    /** Error message if not allowed */
+    error: string | null;
+}
+/**
+ * Branch validation result
+ */
+export interface IBranchValidationResult {
+    /** Whether the branch name is valid */
+    valid: boolean;
+    /** Lane name (kebab-case) or null */
+    lane: string | null;
+    /** WU ID (uppercase) or null */
+    wuid: string | null;
+    /** Error message if invalid */
+    error: string | null;
+}
+/**
+ * WU YAML reader interface
+ */
+export interface IWuYamlReader {
+    /**
+     * Read and parse WU YAML file
+     * @param wuPath - Path to WU YAML file
+     * @param expectedId - Expected WU ID for validation
+     * @returns Parsed WU document
+     */
+    readWU(wuPath: string, expectedId: string): unknown;
+    /**
+     * Read YAML file without ID validation
+     * @param yamlPath - Path to YAML file
+     * @returns Parsed document
+     */
+    readWURaw(yamlPath: string): unknown;
+}
+/**
+ * WU YAML writer interface
+ */
+export interface IWuYamlWriter {
+    /**
+     * Write WU document to file
+     * @param wuPath - Path to WU YAML file
+     * @param doc - Document to write
+     */
+    writeWU(wuPath: string, doc: unknown): void;
+}
+/**
+ * WU state store interface (subset for dependency injection)
+ */
+export interface IWuStateStore {
+    /**
+     * Load state from events file
+     */
+    load(): Promise<void>;
+    /**
+     * Claim a WU (transition to in_progress)
+     * @param wuId - WU identifier
+     * @param lane - Lane name
+     * @param title - WU title
+     */
+    claim(wuId: string, lane: string, title: string): Promise<void>;
+    /**
+     * Complete a WU (transition to done)
+     * @param wuId - WU identifier
+     */
+    complete(wuId: string): Promise<void>;
+    /**
+     * Block a WU (transition to blocked)
+     * @param wuId - WU identifier
+     * @param reason - Block reason
+     */
+    block(wuId: string, reason: string): Promise<void>;
+    /**
+     * Unblock a WU (transition back to in_progress)
+     * @param wuId - WU identifier
+     */
+    unblock(wuId: string): Promise<void>;
+    /**
+     * Release a WU (transition to ready)
+     * @param wuId - WU identifier
+     * @param reason - Release reason
+     */
+    release(wuId: string, reason: string): Promise<void>;
+    /**
+     * Get WU state entry
+     * @param wuId - WU identifier
+     * @returns State entry or undefined
+     */
+    getWUState(wuId: string): {
+        status: string;
+        lane: string;
+        title: string;
+    } | undefined;
+    /**
+     * Get all WU IDs by status
+     * @param status - Status to filter by
+     * @returns Set of WU IDs
+     */
+    getByStatus(status: string): Set<string>;
+    /**
+     * Get all WU IDs by lane
+     * @param lane - Lane to filter by
+     * @returns Set of WU IDs
+     */
+    getByLane(lane: string): Set<string>;
+}
+/**
+ * WU checkpoint interface
+ */
+export interface IWuCheckpointManager {
+    /**
+     * Create a pre-gates checkpoint
+     */
+    createPreGatesCheckpoint(params: {
+        wuId: string;
+        worktreePath: string;
+        branchName: string;
+        gatesPassed?: boolean;
+    }, options?: {
+        baseDir?: string;
+    }): Promise<{
+        checkpointId: string;
+        gatesPassed: boolean;
+    }>;
+    /**
+     * Mark checkpoint as gates passed
+     * @param wuId - WU identifier
+     * @returns True if updated
+     */
+    markGatesPassed(wuId: string, options?: {
+        baseDir?: string;
+    }): boolean;
+    /**
+     * Get checkpoint for a WU
+     * @param wuId - WU identifier
+     * @returns Checkpoint or null
+     */
+    getCheckpoint(wuId: string, options?: {
+        baseDir?: string;
+    }): {
+        gatesPassed: boolean;
+        worktreeHeadSha: string;
+    } | null;
+    /**
+     * Clear checkpoint
+     * @param wuId - WU identifier
+     */
+    clearCheckpoint(wuId: string, options?: {
+        baseDir?: string;
+    }): void;
+    /**
+     * Check if gates can be skipped
+     */
+    canSkipGates(wuId: string, options?: {
+        baseDir?: string;
+        currentHeadSha?: string;
+    }): {
+        canSkip: boolean;
+        reason?: string;
+    };
+}
+/**
+ * WU paths interface
+ */
+export interface IWuPaths {
+    /** Get path to WU YAML file */
+    WU(id: string): string;
+    /** Get path to WU directory */
+    WU_DIR(): string;
+    /** Get path to status.md */
+    STATUS(): string;
+    /** Get path to backlog.md */
+    BACKLOG(): string;
+    /** Get path to stamps directory */
+    STAMPS_DIR(): string;
+    /** Get path to WU done stamp file */
+    STAMP(id: string): string;
+    /** Get path to state directory */
+    STATE_DIR(): string;
+    /** Get path to initiatives directory */
+    INITIATIVES_DIR(): string;
+    /** Get path to worktrees directory */
+    WORKTREES_DIR(): string;
+}

package/dist/ports/wu-helpers.ports.js

@@ -0,0 +1,12 @@
+/**
+ * WU Helpers Port Interfaces
+ *
+ * WU-1102: INIT-003 Phase 2b - Port interfaces for WU helper modules
+ *
+ * Hexagonal Architecture - Input Ports:
+ * These abstractions allow external users to inject custom implementations
+ * for WU lifecycle operations.
+ *
+ * @module ports/wu-helpers
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/core",
-  "version": "1.6.0",
+  "version": "2.1.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.6.0"
+    "@lumenflow/memory": "2.1.0"
   },
   "peerDependenciesMeta": {
     "@lumenflow/memory": {