@lumenflow/core 1.0.0

package/dist/validators/phi-scanner.d.ts

@@ -0,0 +1,58 @@
+/**
+ * PHI (Protected Health Information) Scanner
+ *
+ * Detects potential PHI in content using library-first approach:
+ * - NHS numbers validated with nhs-number-validator (Modulus 11 checksum)
+ * - UK postcodes parsed with postcode library, flagged only in medical context
+ *
+ * Part of WU-1404: PHI Scanner Integration
+ *
+ * @see {@link https://github.com/spikeheap/nhs-number-validator} NHS validation
+ * @see {@link https://github.com/ideal-postcodes/postcode} Postcode parsing
+ */
+/**
+ * Check if a file path should be excluded from PHI scanning
+ *
+ * @param {string|null|undefined} filePath - Path to check
+ * @returns {boolean} True if path should be excluded
+ */
+export declare function isPathExcluded(filePath: any): boolean;
+/**
+ * Options for PHI scanning
+ */
+export interface ScanForPHIOptions {
+    /** File path for exclusion check */
+    filePath?: string;
+}
+/**
+ * Scan content for PHI (Protected Health Information)
+ *
+ * Detects:
+ * - Valid NHS numbers (validated with Modulus 11 checksum)
+ * - UK postcodes in medical context
+ *
+ * @param {string|null|undefined} content - Content to scan
+ * @param {ScanForPHIOptions} [options] - Scan options
+ * @returns {{hasPHI: boolean, matches: Array, warnings: string[]}} Scan result
+ */
+interface PHIMatch {
+    type: string;
+    value: string;
+    startIndex: number;
+    endIndex: number;
+    medicalKeyword?: string;
+}
+export declare function scanForPHI(content: string, options?: ScanForPHIOptions): {
+    hasPHI: boolean;
+    matches: PHIMatch[];
+    warnings: string[];
+    filePath?: string;
+};
+/**
+ * Create a human-readable summary of PHI matches
+ *
+ * @param {Array} matches - PHI matches from scanForPHI
+ * @returns {string} Summary message
+ */
+export declare function formatPHISummary(matches: any): string;
+export {};

package/dist/validators/phi-scanner.js

@@ -0,0 +1,215 @@
+/**
+ * PHI (Protected Health Information) Scanner
+ *
+ * Detects potential PHI in content using library-first approach:
+ * - NHS numbers validated with nhs-number-validator (Modulus 11 checksum)
+ * - UK postcodes parsed with postcode library, flagged only in medical context
+ *
+ * Part of WU-1404: PHI Scanner Integration
+ *
+ * @see {@link https://github.com/spikeheap/nhs-number-validator} NHS validation
+ * @see {@link https://github.com/ideal-postcodes/postcode} Postcode parsing
+ */
+import nhsValidator from 'nhs-number-validator';
+import { isValid as isValidPostcode, parse as parsePostcode } from 'postcode';
+import { PHI_TYPES, MEDICAL_CONTEXT_KEYWORDS, MEDICAL_CONTEXT_WINDOW_SIZE, TEST_NHS_NUMBERS, NHS_TEST_PREFIX, TEST_POSTCODES, TEST_DATA_MARKERS, EXCLUDED_PATH_PATTERNS, NHS_CANDIDATE_PATTERN, } from './phi-constants.js';
+/**
+ * Check if a file path should be excluded from PHI scanning
+ *
+ * @param {string|null|undefined} filePath - Path to check
+ * @returns {boolean} True if path should be excluded
+ */
+export function isPathExcluded(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return false;
+    }
+    return EXCLUDED_PATH_PATTERNS.some((pattern) => pattern.test(filePath));
+}
+/**
+ * Check if content contains test data markers
+ *
+ * @param {string} content - Content to check
+ * @returns {boolean} True if test markers are present
+ */
+function hasTestDataMarkers(content) {
+    const contentLower = content.toLowerCase();
+    return TEST_DATA_MARKERS.some((marker) => contentLower.includes(marker.toLowerCase()));
+}
+/**
+ * Normalize NHS number by removing spaces and dashes
+ *
+ * @param {string} nhsNumber - NHS number with possible formatting
+ * @returns {string} Normalized 10-digit NHS number
+ */
+function normalizeNhsNumber(nhsNumber) {
+    return nhsNumber.replace(/[\s-]/g, '');
+}
+/**
+ * Check if NHS number is a known test number
+ *
+ * @param {string} nhsNumber - Normalized NHS number
+ * @returns {boolean} True if it's a test number
+ */
+function isTestNhsNumber(nhsNumber) {
+    // Check against explicit test numbers
+    if (TEST_NHS_NUMBERS.includes(nhsNumber)) {
+        return true;
+    }
+    // Check for 999 prefix (NHS Digital test range)
+    if (nhsNumber.startsWith(NHS_TEST_PREFIX)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Normalize postcode for comparison (uppercase, no spaces)
+ *
+ * @param {string} postcode - Postcode to normalize
+ * @returns {string} Normalized postcode
+ */
+function normalizePostcode(postcode) {
+    return postcode.toUpperCase().replace(/\s/g, '');
+}
+/**
+ * Check if postcode is a known test postcode
+ *
+ * @param {string} postcode - Postcode to check
+ * @returns {boolean} True if it's a test postcode
+ */
+function isTestPostcode(postcode) {
+    const normalized = normalizePostcode(postcode);
+    return TEST_POSTCODES.some((testPc) => normalizePostcode(testPc) === normalized);
+}
+/**
+ * Check if there's a medical context keyword within the context window
+ *
+ * @param {string} content - Full content
+ * @param {number} postcodeIndex - Index of postcode in content
+ * @param {number} postcodeLength - Length of the postcode string
+ * @returns {{found: boolean, keyword?: string}} Medical context result
+ */
+function findMedicalContext(content, postcodeIndex, postcodeLength) {
+    // Define the window around the postcode
+    const windowStart = Math.max(0, postcodeIndex - MEDICAL_CONTEXT_WINDOW_SIZE);
+    const windowEnd = Math.min(content.length, postcodeIndex + postcodeLength + MEDICAL_CONTEXT_WINDOW_SIZE);
+    const windowContent = content.slice(windowStart, windowEnd).toLowerCase();
+    for (const keyword of MEDICAL_CONTEXT_KEYWORDS) {
+        if (windowContent.includes(keyword.toLowerCase())) {
+            return { found: true, keyword };
+        }
+    }
+    return { found: false };
+}
+/**
+ * Extract potential UK postcodes from content
+ *
+ * UK postcode format is complex - we use the postcode library for validation
+ * but need to extract candidates first. The library's isValid handles edge cases.
+ *
+ * @param {string} content - Content to scan
+ * @returns {Array<{value: string, index: number}>} Postcode candidates with positions
+ */
+function extractPostcodeCandidates(content) {
+    const candidates = [];
+    // UK postcode pattern (simplified - library validates properly)
+    // Format: A(A)N(N) NAA or variations
+    const postcodePattern = /\b([A-Z]{1,2}\d[A-Z\d]?\s*\d[A-Z]{2})\b/gi;
+    let match;
+    while ((match = postcodePattern.exec(content)) !== null) {
+        const candidate = match[1];
+        // Validate with library
+        if (isValidPostcode(candidate)) {
+            const parsed = parsePostcode(candidate);
+            if (parsed.valid) {
+                candidates.push({
+                    value: parsed.postcode, // Normalized postcode
+                    index: match.index,
+                    originalValue: match[1],
+                });
+            }
+        }
+    }
+    return candidates;
+}
+export function scanForPHI(content, options = {}) {
+    const result = {
+        hasPHI: false,
+        matches: [],
+        warnings: [],
+    };
+    // Handle null/undefined/empty content
+    if (!content || typeof content !== 'string' || content.trim() === '') {
+        return result;
+    }
+    // Check path exclusions
+    if (options.filePath && isPathExcluded(options.filePath)) {
+        result.warnings.push(`Path excluded from PHI scanning: ${options.filePath}`);
+        return result;
+    }
+    // Check for test data markers
+    if (hasTestDataMarkers(content)) {
+        result.warnings.push('Test data markers detected - PHI scanning skipped');
+        return result;
+    }
+    // Scan for NHS numbers
+    const nhsCandidates = [...content.matchAll(NHS_CANDIDATE_PATTERN)];
+    for (const match of nhsCandidates) {
+        const rawNumber = match[1];
+        const normalized = normalizeNhsNumber(rawNumber);
+        // Skip if it's a test number
+        if (isTestNhsNumber(normalized)) {
+            continue;
+        }
+        // Validate with library (Modulus 11 checksum)
+        if (nhsValidator.validate(normalized)) {
+            result.matches.push({
+                type: PHI_TYPES.NHS_NUMBER,
+                value: normalized,
+                startIndex: match.index,
+                endIndex: match.index + rawNumber.length,
+            });
+        }
+    }
+    // Scan for postcodes in medical context
+    const postcodeCandidates = extractPostcodeCandidates(content);
+    for (const candidate of postcodeCandidates) {
+        // Skip test postcodes
+        if (isTestPostcode(candidate.value)) {
+            continue;
+        }
+        // Check for medical context
+        const medicalContext = findMedicalContext(content, candidate.index, candidate.value.length);
+        if (medicalContext.found) {
+            result.matches.push({
+                type: PHI_TYPES.POSTCODE_MEDICAL_CONTEXT,
+                value: candidate.value,
+                startIndex: candidate.index,
+                endIndex: candidate.index + candidate.originalValue.length,
+                medicalKeyword: medicalContext.keyword,
+            });
+        }
+    }
+    result.hasPHI = result.matches.length > 0;
+    return result;
+}
+/**
+ * Create a human-readable summary of PHI matches
+ *
+ * @param {Array} matches - PHI matches from scanForPHI
+ * @returns {string} Summary message
+ */
+export function formatPHISummary(matches) {
+    if (matches.length === 0) {
+        return 'No PHI detected';
+    }
+    const nhsCount = matches.filter((m) => m.type === PHI_TYPES.NHS_NUMBER).length;
+    const postcodeCount = matches.filter((m) => m.type === PHI_TYPES.POSTCODE_MEDICAL_CONTEXT).length;
+    const parts = [];
+    if (nhsCount > 0) {
+        parts.push(`${nhsCount} NHS number${nhsCount > 1 ? 's' : ''}`);
+    }
+    if (postcodeCount > 0) {
+        parts.push(`${postcodeCount} postcode${postcodeCount > 1 ? 's' : ''} in medical context`);
+    }
+    return `PHI detected: ${parts.join(', ')}`;
+}

package/dist/worktree-ownership.d.ts

@@ -0,0 +1,50 @@
+/**
+ * WU-2278: Worktree Ownership Validation
+ *
+ * Validates that a WU can only clean up its own worktree.
+ * Prevents cross-agent worktree deletion during parallel execution.
+ *
+ * Note: No external library exists for LumenFlow-specific worktree ownership
+ * validation - this is internal workflow tooling.
+ *
+ * @module worktree-ownership
+ */
+/**
+ * Extract WU ID from worktree path
+ *
+ * Worktree paths follow pattern: worktrees/<lane>-wu-<id>
+ * Examples:
+ *   - worktrees/operations-wu-100 -> WU-100
+ *   - worktrees/operations-tooling-wu-2278 -> WU-2278
+ *   - worktrees/experience-chat-wu-500 -> WU-500
+ *
+ * @param {string} worktreePath - Path to worktree
+ * @returns {string|null} Extracted WU ID (uppercase) or null if not found
+ */
+export declare function extractWUFromWorktreePath(worktreePath: any): string;
+/**
+ * Validate that the WU can safely clean up the given worktree
+ *
+ * Blocks deletion when:
+ * - Worktree path contains a different WU ID
+ *
+ * Allows deletion when:
+ * - Worktree path is null/undefined (nothing to clean up)
+ * - Worktree path matches the WU ID
+ * - Worktree path doesn't follow WU naming convention (manual worktree)
+ *
+ * @param {Object} params - Validation parameters
+ * @param {string|null|undefined} params.worktreePath - Path to worktree
+ * @param {string} params.wuId - WU ID attempting cleanup (e.g., "WU-100")
+ * @returns {{ valid: boolean, error?: string }} Validation result
+ */
+export declare function validateWorktreeOwnership({ worktreePath, wuId }: {
+    worktreePath: any;
+    wuId: any;
+}): {
+    valid: boolean;
+    error?: undefined;
+} | {
+    valid: boolean;
+    error: string;
+};

package/dist/worktree-ownership.js

@@ -0,0 +1,74 @@
+/**
+ * WU-2278: Worktree Ownership Validation
+ *
+ * Validates that a WU can only clean up its own worktree.
+ * Prevents cross-agent worktree deletion during parallel execution.
+ *
+ * Note: No external library exists for LumenFlow-specific worktree ownership
+ * validation - this is internal workflow tooling.
+ *
+ * @module worktree-ownership
+ */
+/**
+ * Extract WU ID from worktree path
+ *
+ * Worktree paths follow pattern: worktrees/<lane>-wu-<id>
+ * Examples:
+ *   - worktrees/operations-wu-100 -> WU-100
+ *   - worktrees/operations-tooling-wu-2278 -> WU-2278
+ *   - worktrees/experience-chat-wu-500 -> WU-500
+ *
+ * @param {string} worktreePath - Path to worktree
+ * @returns {string|null} Extracted WU ID (uppercase) or null if not found
+ */
+export function extractWUFromWorktreePath(worktreePath) {
+    if (!worktreePath || typeof worktreePath !== 'string') {
+        return null;
+    }
+    // Match wu-<id> pattern at end of path (case insensitive)
+    const match = worktreePath.match(/wu-(\d+)(?:\/)?$/i);
+    if (!match) {
+        return null;
+    }
+    return `WU-${match[1]}`;
+}
+/**
+ * Validate that the WU can safely clean up the given worktree
+ *
+ * Blocks deletion when:
+ * - Worktree path contains a different WU ID
+ *
+ * Allows deletion when:
+ * - Worktree path is null/undefined (nothing to clean up)
+ * - Worktree path matches the WU ID
+ * - Worktree path doesn't follow WU naming convention (manual worktree)
+ *
+ * @param {Object} params - Validation parameters
+ * @param {string|null|undefined} params.worktreePath - Path to worktree
+ * @param {string} params.wuId - WU ID attempting cleanup (e.g., "WU-100")
+ * @returns {{ valid: boolean, error?: string }} Validation result
+ */
+export function validateWorktreeOwnership({ worktreePath, wuId }) {
+    // No worktree path = nothing to validate
+    if (!worktreePath) {
+        return { valid: true };
+    }
+    const worktreeWuId = extractWUFromWorktreePath(worktreePath);
+    // If worktree doesn't follow WU naming, allow cleanup (manual worktree)
+    if (!worktreeWuId) {
+        return {
+            valid: false,
+            error: `Worktree ownership mismatch: cannot determine owner of ${worktreePath}`,
+        };
+    }
+    // Normalize WU IDs for comparison (case insensitive)
+    const normalizedWorktreeId = worktreeWuId.toUpperCase();
+    const normalizedWuId = wuId.toUpperCase();
+    if (normalizedWorktreeId !== normalizedWuId) {
+        return {
+            valid: false,
+            error: `Worktree ownership mismatch: worktree belongs to ${normalizedWorktreeId}, but ${normalizedWuId} attempted cleanup. This could delete another agent's work.`,
+        };
+    }
+    return { valid: true };
+}

package/dist/worktree-scanner.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Worktree Scanner (WU-1748)
+ *
+ * Scans existing git worktrees to detect uncommitted changes.
+ * Provides cross-agent visibility for abandoned WU work.
+ *
+ * Features:
+ * - Parses git worktree list output
+ * - Detects uncommitted changes per worktree
+ * - Reports last activity timestamp
+ * - Identifies potentially abandoned WUs
+ *
+ * @see {@link tools/lib/__tests__/worktree-scanner.test.mjs} - Tests
+ */
+/**
+ * @typedef {object} WorktreeInfo
+ * @property {string} path - Absolute path to worktree
+ * @property {string} sha - Current commit SHA
+ * @property {string} branch - Branch name or "(detached HEAD)"
+ * @property {boolean} isMain - Whether this is the main worktree
+ * @property {string} [wuId] - WU ID if this is a lane worktree
+ */
+/**
+ * @typedef {object} WorktreeStatus
+ * @property {boolean} hasUncommittedChanges - Whether there are uncommitted changes
+ * @property {number} uncommittedFileCount - Number of uncommitted files
+ * @property {string[]} uncommittedFiles - List of uncommitted file paths
+ * @property {string} lastActivityTimestamp - ISO timestamp of last git activity
+ * @property {string} [error] - Error message if git commands failed
+ */
+/**
+ * @typedef {object} WorktreeScanResult
+ * @property {(WorktreeInfo & WorktreeStatus)[]} worktrees - All WU worktrees with status
+ * @property {(WorktreeInfo & WorktreeStatus)[]} worktreesWithUncommittedWork - Worktrees with uncommitted changes
+ * @property {object} summary - Summary statistics
+ * @property {number} summary.totalWorktrees - Total number of WU worktrees
+ * @property {number} summary.withUncommittedChanges - Number with uncommitted changes
+ * @property {number} summary.totalUncommittedFiles - Total uncommitted files across all worktrees
+ */
+/**
+ * Parses git worktree list output into structured data.
+ *
+ * @param {string} output - Raw output from `git worktree list`
+ * @returns {WorktreeInfo[]} Parsed worktree information
+ *
+ * @example
+ * const info = parseWorktreeList('/home/user/project abc1234 [main]');
+ * // Returns: [{ path: '/home/user/project', sha: 'abc1234', branch: 'main', isMain: true }]
+ */
+export declare function parseWorktreeList(output: any): any[];
+/**
+ * Gets the status of a single worktree including uncommitted changes.
+ *
+ * @param {string} worktreePath - Path to the worktree
+ * @param {object} [options] - Options
+ * @param {WorktreeScannerOptions} [options] - Options
+ * @returns {Promise<WorktreeStatus>} Worktree status
+ *
+ * @example
+ * const status = await getWorktreeStatus('/path/to/worktree');
+ * if (status.hasUncommittedChanges) {
+ *   console.log(`Found ${status.uncommittedFileCount} uncommitted files`);
+ * }
+ */
+interface WorktreeScannerOptions {
+    /** Custom exec function for testing */
+    execAsync?: (cmd: string) => Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+}
+export declare function getWorktreeStatus(worktreePath: any, options?: WorktreeScannerOptions): Promise<{
+    hasUncommittedChanges: boolean;
+    uncommittedFileCount: number;
+    uncommittedFiles: string[];
+    lastActivityTimestamp: string;
+    error?: string;
+}>;
+/**
+ * Scans all worktrees and returns their status.
+ *
+ * Excludes the main worktree and focuses on WU worktrees (lane branches).
+ *
+ * @param {string} basePath - Path to main repository
+ * @param {WorktreeScannerOptions} [options] - Options
+ * @returns {Promise<WorktreeScanResult>} Scan results with all worktrees and summary
+ *
+ * @example
+ * const result = await scanWorktrees('/path/to/repo');
+ * for (const wt of result.worktreesWithUncommittedWork) {
+ *   console.log(`${wt.wuId}: ${wt.uncommittedFileCount} uncommitted files`);
+ * }
+ */
+export declare function scanWorktrees(basePath: any, options?: WorktreeScannerOptions): Promise<{
+    worktrees: any[];
+    worktreesWithUncommittedWork: any[];
+    summary: {
+        totalWorktrees: number;
+        withUncommittedChanges: number;
+        totalUncommittedFiles: any;
+    };
+}>;
+export {};

package/dist/worktree-scanner.js

@@ -0,0 +1,168 @@
+/**
+ * Worktree Scanner (WU-1748)
+ *
+ * Scans existing git worktrees to detect uncommitted changes.
+ * Provides cross-agent visibility for abandoned WU work.
+ *
+ * Features:
+ * - Parses git worktree list output
+ * - Detects uncommitted changes per worktree
+ * - Reports last activity timestamp
+ * - Identifies potentially abandoned WUs
+ *
+ * @see {@link tools/lib/__tests__/worktree-scanner.test.mjs} - Tests
+ */
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+const execAsync = promisify(exec);
+/**
+ * Regex pattern to extract WU ID from lane branch name
+ * Matches patterns like: lane/operations/wu-1234, lane/operations-tooling/wu-1234
+ */
+const WU_ID_PATTERN = /wu-(\d+)$/i;
+/**
+ * Regex pattern to parse git worktree list output line
+ * Format: /path/to/worktree  SHA1 [branch] or (detached HEAD)
+ */
+const WORKTREE_LINE_PATTERN = /^(\S+)\s+(\S+)\s+(?:\[([^\]]+)\]|\(([^)]+)\))$/;
+/**
+ * @typedef {object} WorktreeInfo
+ * @property {string} path - Absolute path to worktree
+ * @property {string} sha - Current commit SHA
+ * @property {string} branch - Branch name or "(detached HEAD)"
+ * @property {boolean} isMain - Whether this is the main worktree
+ * @property {string} [wuId] - WU ID if this is a lane worktree
+ */
+/**
+ * @typedef {object} WorktreeStatus
+ * @property {boolean} hasUncommittedChanges - Whether there are uncommitted changes
+ * @property {number} uncommittedFileCount - Number of uncommitted files
+ * @property {string[]} uncommittedFiles - List of uncommitted file paths
+ * @property {string} lastActivityTimestamp - ISO timestamp of last git activity
+ * @property {string} [error] - Error message if git commands failed
+ */
+/**
+ * @typedef {object} WorktreeScanResult
+ * @property {(WorktreeInfo & WorktreeStatus)[]} worktrees - All WU worktrees with status
+ * @property {(WorktreeInfo & WorktreeStatus)[]} worktreesWithUncommittedWork - Worktrees with uncommitted changes
+ * @property {object} summary - Summary statistics
+ * @property {number} summary.totalWorktrees - Total number of WU worktrees
+ * @property {number} summary.withUncommittedChanges - Number with uncommitted changes
+ * @property {number} summary.totalUncommittedFiles - Total uncommitted files across all worktrees
+ */
+/**
+ * Parses git worktree list output into structured data.
+ *
+ * @param {string} output - Raw output from `git worktree list`
+ * @returns {WorktreeInfo[]} Parsed worktree information
+ *
+ * @example
+ * const info = parseWorktreeList('/home/user/project abc1234 [main]');
+ * // Returns: [{ path: '/home/user/project', sha: 'abc1234', branch: 'main', isMain: true }]
+ */
+export function parseWorktreeList(output) {
+    if (!output || !output.trim()) {
+        return [];
+    }
+    const lines = output.trim().split('\n');
+    const worktrees = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const match = trimmed.match(WORKTREE_LINE_PATTERN);
+        if (!match)
+            continue;
+        const [, path, sha, bracketBranch, parenBranch] = match;
+        const branch = bracketBranch || parenBranch;
+        const isMain = branch === 'main' || branch === 'master';
+        /** @type {WorktreeInfo} */
+        const info = {
+            path,
+            sha,
+            branch,
+            isMain,
+        };
+        // Extract WU ID from lane branch name
+        const wuMatch = branch.match(WU_ID_PATTERN);
+        if (wuMatch) {
+            info.wuId = `WU-${wuMatch[1]}`;
+        }
+        worktrees.push(info);
+    }
+    return worktrees;
+}
+export async function getWorktreeStatus(worktreePath, options = {}) {
+    const runCmd = options.execAsync || execAsync;
+    /** @type {WorktreeStatus} */
+    const status = {
+        hasUncommittedChanges: false,
+        uncommittedFileCount: 0,
+        uncommittedFiles: [],
+        lastActivityTimestamp: '',
+    };
+    try {
+        // Get uncommitted changes via git status --porcelain
+        const statusResult = await runCmd(`git -C "${worktreePath}" status --porcelain`);
+        // Note: Don't trim() the whole output as it would remove leading space from first line
+        // Git status --porcelain format: XY filename (2 chars + space + path)
+        const statusOutput = statusResult.stdout;
+        if (statusOutput && statusOutput.trim()) {
+            const files = statusOutput
+                .split('\n')
+                .filter((line) => line.length > 3) // Filter empty lines
+                .map((line) => line.slice(3).trim()); // Remove XY prefix and trim path
+            status.uncommittedFiles = files;
+            status.uncommittedFileCount = files.length;
+            status.hasUncommittedChanges = files.length > 0;
+        }
+        // Get last activity timestamp from git log
+        const logResult = await runCmd(`git -C "${worktreePath}" log -1 --format=%aI 2>/dev/null || echo ""`);
+        status.lastActivityTimestamp = logResult.stdout.trim();
+    }
+    catch (error) {
+        status.error = error instanceof Error ? error.message : String(error);
+    }
+    return status;
+}
+/**
+ * Scans all worktrees and returns their status.
+ *
+ * Excludes the main worktree and focuses on WU worktrees (lane branches).
+ *
+ * @param {string} basePath - Path to main repository
+ * @param {WorktreeScannerOptions} [options] - Options
+ * @returns {Promise<WorktreeScanResult>} Scan results with all worktrees and summary
+ *
+ * @example
+ * const result = await scanWorktrees('/path/to/repo');
+ * for (const wt of result.worktreesWithUncommittedWork) {
+ *   console.log(`${wt.wuId}: ${wt.uncommittedFileCount} uncommitted files`);
+ * }
+ */
+export async function scanWorktrees(basePath, options = {}) {
+    const runCmd = options.execAsync || execAsync;
+    // Get worktree list
+    const listResult = await runCmd(`git -C "${basePath}" worktree list`);
+    const allWorktrees = parseWorktreeList(listResult.stdout);
+    // Filter to WU worktrees only (exclude main)
+    const wuWorktrees = allWorktrees.filter((wt) => !wt.isMain && wt.wuId);
+    // Get status for each WU worktree
+    const worktreesWithStatus = await Promise.all(wuWorktrees.map(async (wt) => {
+        const status = await getWorktreeStatus(wt.path, { execAsync: runCmd });
+        return { ...wt, ...status };
+    }));
+    // Filter to those with uncommitted changes
+    const worktreesWithUncommittedWork = worktreesWithStatus.filter((wt) => wt.hasUncommittedChanges);
+    // Calculate summary
+    const summary = {
+        totalWorktrees: worktreesWithStatus.length,
+        withUncommittedChanges: worktreesWithUncommittedWork.length,
+        totalUncommittedFiles: worktreesWithStatus.reduce((sum, wt) => sum + wt.uncommittedFileCount, 0),
+    };
+    return {
+        worktrees: worktreesWithStatus,
+        worktreesWithUncommittedWork,
+        summary,
+    };
+}