@lumenflow/core 1.0.0

package/dist/micro-worktree.js

@@ -0,0 +1,427 @@
+/**
+ * Micro-Worktree Operations
+ *
+ * Race-safe micro-worktree isolation pattern extracted from wu-create.mjs (WU-1262).
+ * Provides shared infrastructure for commands that need to modify main branch
+ * atomically without switching checkout.
+ *
+ * Part of WU-1262: Race-safe WU creation using micro-worktrees
+ * Extended in WU-1274: Add wu:edit command for spec-only changes
+ * Extended in WU-1439: Migrate initiative:create and wu:create to shared helper
+ *
+ * Pattern:
+ * 1. Create temp branch without switching main checkout
+ * 2. Create micro-worktree in /tmp pointing to temp branch
+ * 3. Perform operations in micro-worktree
+ * 4. FF-only merge temp branch to main (retry with rebase if main moved)
+ * 5. Push to origin
+ * 6. Cleanup (always, even on failure)
+ *
+ * Benefits:
+ * - Main checkout never switches branches (no impact on other agents)
+ * - Race conditions handled via rebase+retry (up to MAX_MERGE_RETRIES attempts)
+ * - Cleanup guaranteed even on failure
+ *
+ * Consumers:
+ * @see {@link tools/wu-create.mjs} - WU creation (WU-1262, WU-1439)
+ * @see {@link tools/wu-edit.mjs} - Spec edits (WU-1274)
+ * @see {@link tools/initiative-create.mjs} - Initiative creation (WU-1439)
+ */
+import { getGitForCwd, createGitForPath } from './git-adapter.js';
+import { existsSync, rmSync, mkdtempSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { BRANCHES, REMOTES, GIT_REFS, PKG_MANAGER, SCRIPTS, PRETTIER_FLAGS, STDIO_MODES, } from './wu-constants.js';
+/**
+ * Maximum retry attempts for ff-only merge when main moves
+ *
+ * This handles race conditions when multiple agents run wu:create or wu:edit
+ * concurrently. Each retry fetches latest main and rebases.
+ */
+export const MAX_MERGE_RETRIES = 3;
+/**
+ * Default log prefix for micro-worktree operations
+ *
+ * Extracted to constant to satisfy sonarjs/no-duplicate-string rule.
+ */
+export const DEFAULT_LOG_PREFIX = '[micro-wt]';
+/**
+ * Temp branch prefix for micro-worktree operations
+ *
+ * @param {string} operation - Operation name (e.g., 'wu-create', 'wu-edit')
+ * @param {string} id - WU ID (e.g., 'wu-123')
+ * @returns {string} Temp branch name (e.g., 'tmp/wu-create/wu-123')
+ */
+export function getTempBranchName(operation, id) {
+    return `${BRANCHES.TEMP_PREFIX}${operation}/${id.toLowerCase()}`;
+}
+/**
+ * Create micro-worktree in /tmp directory
+ *
+ * @param {string} prefix - Directory prefix (e.g., 'wu-create-', 'wu-edit-')
+ * @returns {string} Path to created micro-worktree directory
+ */
+export function createMicroWorktreeDir(prefix) {
+    return mkdtempSync(join(tmpdir(), prefix));
+}
+/**
+ * Parse git worktree list output to find worktrees by branch
+ *
+ * WU-2237: Helper to parse porcelain format output from `git worktree list --porcelain`
+ *
+ * @param {string} worktreeListOutput - Output from git worktree list --porcelain
+ * @param {string} branchName - Branch name to search for (e.g., 'tmp/wu-create/wu-123')
+ * @returns {string|null} Worktree path if found, null otherwise
+ */
+export function findWorktreeByBranch(worktreeListOutput, branchName) {
+    const branchRef = `refs/heads/${branchName}`;
+    const lines = worktreeListOutput.split('\n');
+    let currentWorktreePath = null;
+    for (const line of lines) {
+        if (line.startsWith('worktree ')) {
+            currentWorktreePath = line.substring('worktree '.length);
+        }
+        else if (line.startsWith('branch ') && line.substring('branch '.length) === branchRef) {
+            return currentWorktreePath;
+        }
+        else if (line === '') {
+            currentWorktreePath = null;
+        }
+    }
+    return null;
+}
+/**
+ * Clean up orphaned micro-worktree and temp branch from a previous interrupted operation
+ *
+ * WU-2237: Before creating a new micro-worktree, detect and clean any existing temp
+ * branch/worktree for the same operation+WU ID. This handles scenarios where:
+ * - A previous wu:create/wu:edit was interrupted (timeout/crash)
+ * - The temp branch and /tmp worktree were left behind
+ * - A subsequent operation would fail with 'branch already exists'
+ *
+ * This function is idempotent - safe to call even when no orphans exist.
+ *
+ * @param {string} operation - Operation name (e.g., 'wu-create', 'wu-edit')
+ * @param {string} id - WU ID (e.g., 'WU-123')
+ * @param {Object} gitAdapter - GitAdapter instance to use (for testability)
+ * @param {string} logPrefix - Log prefix for console output
+ * @returns {Promise<{cleanedWorktree: boolean, cleanedBranch: boolean}>} Cleanup status
+ */
+export async function cleanupOrphanedMicroWorktree(operation, id, gitAdapter, logPrefix = DEFAULT_LOG_PREFIX) {
+    const tempBranchName = getTempBranchName(operation, id);
+    let cleanedWorktree = false;
+    let cleanedBranch = false;
+    // Step 1: Check git worktree list for any worktree on this temp branch
+    try {
+        const worktreeListOutput = await gitAdapter.worktreeList();
+        const orphanWorktreePath = findWorktreeByBranch(worktreeListOutput, tempBranchName);
+        if (orphanWorktreePath) {
+            console.log(`${logPrefix} Found orphaned worktree for ${tempBranchName}: ${orphanWorktreePath}`);
+            try {
+                await gitAdapter.worktreeRemove(orphanWorktreePath, { force: true });
+                console.log(`${logPrefix} ✅ Removed orphaned worktree: ${orphanWorktreePath}`);
+                cleanedWorktree = true;
+            }
+            catch (err) {
+                console.warn(`${logPrefix} ⚠️  Could not remove orphaned worktree: ${err.message}`);
+                // Try filesystem cleanup as fallback
+                tryFilesystemCleanup(orphanWorktreePath);
+                cleanedWorktree = true;
+            }
+        }
+    }
+    catch (err) {
+        console.warn(`${logPrefix} ⚠️  Could not check worktree list: ${err.message}`);
+    }
+    // Step 2: Check if the temp branch exists and delete it
+    try {
+        const branchExists = await gitAdapter.branchExists(tempBranchName);
+        if (branchExists) {
+            console.log(`${logPrefix} Found orphaned temp branch: ${tempBranchName}`);
+            await gitAdapter.deleteBranch(tempBranchName, { force: true });
+            console.log(`${logPrefix} ✅ Deleted orphaned temp branch: ${tempBranchName}`);
+            cleanedBranch = true;
+        }
+    }
+    catch (err) {
+        console.warn(`${logPrefix} ⚠️  Could not delete orphaned branch: ${err.message}`);
+    }
+    return { cleanedWorktree, cleanedBranch };
+}
+/**
+ * Try to remove a worktree path via filesystem as fallback
+ *
+ * WU-2237: Extracted helper to reduce cognitive complexity.
+ *
+ * @param {string} worktreePath - Path to remove
+ */
+function tryFilesystemCleanup(worktreePath) {
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool with validated worktree path
+        if (existsSync(worktreePath)) {
+            rmSync(worktreePath, { recursive: true, force: true });
+        }
+    }
+    catch {
+        // Ignore filesystem cleanup errors
+    }
+}
+/**
+ * Remove a worktree using git, with filesystem fallback
+ *
+ * WU-2237: Extracted helper to reduce cognitive complexity.
+ *
+ * @param {Object} gitAdapter - Git adapter instance
+ * @param {string} worktreePath - Path to worktree
+ * @param {string} logPrefix - Log prefix
+ * @param {string} [contextLabel] - Optional label for logging (e.g., 'registered')
+ */
+async function removeWorktreeSafe(gitAdapter, worktreePath, logPrefix, contextLabel = '') {
+    const label = contextLabel ? ` ${contextLabel}` : '';
+    try {
+        await gitAdapter.worktreeRemove(worktreePath, { force: true });
+        if (contextLabel) {
+            console.log(`${logPrefix} ✅ Removed${label} worktree: ${worktreePath}`);
+        }
+    }
+    catch (err) {
+        console.warn(`${logPrefix} ⚠️  Could not remove${label} worktree: ${err.message}`);
+        tryFilesystemCleanup(worktreePath);
+    }
+}
+/**
+ * Cleanup micro-worktree and temp branch
+ *
+ * Runs even on failure to prevent orphaned resources.
+ * Safe to call multiple times (idempotent).
+ *
+ * WU-2237: Enhanced to also check git worktree list for registered worktrees
+ * on the temp branch, in case the worktree path differs from what was expected.
+ *
+ * @param {string} worktreePath - Path to micro-worktree
+ * @param {string} branchName - Temp branch name
+ * @param {string} logPrefix - Log prefix for console output
+ */
+export async function cleanupMicroWorktree(worktreePath, branchName, logPrefix = DEFAULT_LOG_PREFIX) {
+    console.log(`${logPrefix} Cleaning up micro-worktree...`);
+    const mainGit = getGitForCwd();
+    // Remove the known worktree path first (must be done before deleting branch)
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool with validated worktree path
+    if (existsSync(worktreePath)) {
+        await removeWorktreeSafe(mainGit, worktreePath, logPrefix);
+    }
+    // WU-2237: Also check git worktree list for any registered worktrees on this branch
+    await cleanupRegisteredWorktreeForBranch(mainGit, branchName, worktreePath, logPrefix);
+    // Delete temp branch
+    await deleteBranchSafe(mainGit, branchName, logPrefix);
+    console.log(`${logPrefix} ✅ Cleanup complete`);
+}
+/**
+ * Clean up any registered worktree for a branch that differs from the expected path
+ *
+ * WU-2237: Extracted helper to reduce cognitive complexity.
+ *
+ * @param {Object} gitAdapter - Git adapter instance
+ * @param {string} branchName - Branch name to search for
+ * @param {string} expectedPath - Expected worktree path (skip if matches)
+ * @param {string} logPrefix - Log prefix
+ */
+async function cleanupRegisteredWorktreeForBranch(gitAdapter, branchName, expectedPath, logPrefix) {
+    try {
+        const worktreeListOutput = await gitAdapter.worktreeList();
+        const registeredPath = findWorktreeByBranch(worktreeListOutput, branchName);
+        if (registeredPath && registeredPath !== expectedPath) {
+            console.log(`${logPrefix} Found additional registered worktree: ${registeredPath}`);
+            await removeWorktreeSafe(gitAdapter, registeredPath, logPrefix, 'registered');
+        }
+    }
+    catch (err) {
+        console.warn(`${logPrefix} ⚠️  Could not check worktree list: ${err.message}`);
+    }
+}
+/**
+ * Delete a branch safely, ignoring errors
+ *
+ * WU-2237: Extracted helper to reduce cognitive complexity.
+ *
+ * @param {Object} gitAdapter - Git adapter instance
+ * @param {string} branchName - Branch to delete
+ * @param {string} logPrefix - Log prefix
+ */
+async function deleteBranchSafe(gitAdapter, branchName, logPrefix) {
+    try {
+        const branchExists = await gitAdapter.branchExists(branchName);
+        if (branchExists) {
+            await gitAdapter.deleteBranch(branchName, { force: true });
+        }
+    }
+    catch (err) {
+        console.warn(`${logPrefix} ⚠️  Could not delete branch: ${err.message}`);
+    }
+}
+/**
+ * Stage changes including deletions in micro-worktree
+ *
+ * WU-1813: Uses addWithDeletions to properly stage tracked file deletions.
+ * This replaces the previous pattern of using gitWorktree.add(files) which
+ * could miss deletions when files were removed.
+ *
+ * @param {Object} gitWorktree - GitAdapter instance for the worktree
+ * @param {string[]|undefined} files - Files to stage (undefined/empty = stage all)
+ * @returns {Promise<void>}
+ */
+export async function stageChangesWithDeletions(gitWorktree, files) {
+    // Normalise undefined/null to empty array for addWithDeletions
+    const filesToStage = files || [];
+    await gitWorktree.addWithDeletions(filesToStage);
+}
+/**
+ * Format files using prettier before committing
+ *
+ * WU-1435: Ensures committed files pass format gates.
+ * Runs prettier --write on specified files within the micro-worktree.
+ *
+ * @param {string[]} files - Relative file paths to format
+ * @param {string} worktreePath - Path to the micro-worktree
+ * @param {string} logPrefix - Log prefix for console output
+ */
+export async function formatFiles(files, worktreePath, logPrefix = DEFAULT_LOG_PREFIX) {
+    if (!files || files.length === 0) {
+        return;
+    }
+    console.log(`${logPrefix} Formatting ${files.length} file(s)...`);
+    // Build absolute paths within the worktree
+    const absolutePaths = files.map((f) => join(worktreePath, f));
+    const pathArgs = absolutePaths.map((p) => JSON.stringify(p)).join(' ');
+    try {
+        execSync(`${PKG_MANAGER} ${SCRIPTS.PRETTIER} ${PRETTIER_FLAGS.WRITE} ${pathArgs}`, {
+            encoding: 'utf-8',
+            stdio: STDIO_MODES.PIPE,
+            cwd: worktreePath,
+        });
+        console.log(`${logPrefix} ✅ Files formatted`);
+    }
+    catch (err) {
+        // Log warning but don't fail - some files may not need formatting
+        console.warn(`${logPrefix} ⚠️  Formatting warning: ${err.message}`);
+    }
+}
+/**
+ * Merge temp branch to main with ff-only and retry logic
+ *
+ * Handles race conditions when main branch advances between operation start
+ * and merge attempt. Retries with rebase up to MAX_MERGE_RETRIES times.
+ *
+ * @param {string} tempBranchName - Temp branch to merge
+ * @param {string} microWorktreePath - Path to micro-worktree (for rebase)
+ * @param {string} logPrefix - Log prefix for console output
+ * @throws {Error} If merge fails after all retries
+ */
+export async function mergeWithRetry(tempBranchName, microWorktreePath, logPrefix = DEFAULT_LOG_PREFIX) {
+    const gitWorktree = createGitForPath(microWorktreePath);
+    const mainGit = getGitForCwd();
+    for (let attempt = 1; attempt <= MAX_MERGE_RETRIES; attempt++) {
+        try {
+            console.log(`${logPrefix} Merging to main (attempt ${attempt}/${MAX_MERGE_RETRIES})...`);
+            await mainGit.merge(tempBranchName, { ffOnly: true });
+            console.log(`${logPrefix} ✅ Merged to main`);
+            return;
+        }
+        catch (mergeErr) {
+            if (attempt < MAX_MERGE_RETRIES) {
+                console.log(`${logPrefix} ⚠️  FF-only merge failed (main moved). Rebasing...`);
+                // Fetch latest main and rebase temp branch
+                await mainGit.fetch(REMOTES.ORIGIN, BRANCHES.MAIN);
+                await mainGit.merge(`${REMOTES.ORIGIN}/${BRANCHES.MAIN}`, { ffOnly: true }); // Update local main
+                await gitWorktree.rebase(BRANCHES.MAIN);
+            }
+            else {
+                throw new Error(`FF-only merge failed after ${MAX_MERGE_RETRIES} attempts. ` +
+                    `Main branch may have significant divergence.\n` +
+                    `Error: ${mergeErr.message}`);
+            }
+        }
+    }
+}
+/**
+ * Execute an operation in a micro-worktree with full isolation
+ *
+ * This is the main entry point for micro-worktree operations.
+ * Handles the full lifecycle: create temp branch, create worktree,
+ * execute operation, merge, push, and cleanup.
+ *
+ * WU-1435: Added pushOnly option to keep local main pristine.
+ * WU-2237: Added pre-creation cleanup of orphaned temp branches/worktrees.
+ *
+ * @param {Object} options - Options for the operation
+ * @param {string} options.operation - Operation name (e.g., 'wu-create', 'wu-edit')
+ * @param {string} options.id - WU ID (e.g., 'WU-123')
+ * @param {string} options.logPrefix - Log prefix for console output
+ * @param {boolean} [options.pushOnly=false] - Skip local main merge, push directly to origin/main
+ * @param {Function} options.execute - Async function to execute in micro-worktree
+ *   Receives: { worktreePath: string, gitWorktree: GitAdapter }
+ *   Should return: { commitMessage: string, files: string[] }
+ * @returns {Promise<Object>} Result with ref property for worktree creation
+ * @throws {Error} If any step fails (cleanup still runs)
+ */
+export async function withMicroWorktree(options) {
+    const { operation, id, logPrefix = `[${operation}]`, execute, pushOnly = false } = options;
+    const mainGit = getGitForCwd();
+    // WU-2237: Clean up any orphaned temp branch/worktree from previous interrupted operations
+    // This makes the operation idempotent - a retry after crash/timeout will succeed
+    await cleanupOrphanedMicroWorktree(operation, id, mainGit, logPrefix);
+    const tempBranchName = getTempBranchName(operation, id);
+    const microWorktreePath = createMicroWorktreeDir(`${operation}-`);
+    console.log(`${logPrefix} Using micro-worktree isolation (WU-1262)`);
+    console.log(`${logPrefix} Temp branch: ${tempBranchName}`);
+    console.log(`${logPrefix} Micro-worktree: ${microWorktreePath}`);
+    if (pushOnly) {
+        console.log(`${logPrefix} Push-only mode: local main will not be modified (WU-1435)`);
+    }
+    try {
+        // Step 1: Create temp branch without switching
+        console.log(`${logPrefix} Creating temp branch...`);
+        await mainGit.createBranchNoCheckout(tempBranchName, BRANCHES.MAIN);
+        // Step 2: Create micro-worktree pointing to temp branch
+        console.log(`${logPrefix} Creating micro-worktree...`);
+        await mainGit.worktreeAddExisting(microWorktreePath, tempBranchName);
+        // Step 3: Execute the operation in micro-worktree
+        const gitWorktree = createGitForPath(microWorktreePath);
+        const result = await execute({ worktreePath: microWorktreePath, gitWorktree });
+        // Step 4: Format files before committing (WU-1435)
+        await formatFiles(result.files, microWorktreePath, logPrefix);
+        // Step 5: Stage and commit in micro-worktree
+        // WU-1813: Use stageChangesWithDeletions to properly handle file deletions
+        console.log(`${logPrefix} Staging changes (including deletions)...`);
+        await stageChangesWithDeletions(gitWorktree, result.files);
+        console.log(`${logPrefix} Committing in micro-worktree...`);
+        await gitWorktree.commit(result.commitMessage);
+        console.log(`${logPrefix} ✅ Committed: ${result.commitMessage}`);
+        // Step 6: Push to origin (different paths for pushOnly vs standard)
+        if (pushOnly) {
+            // WU-1435: Push directly to origin/main without touching local main
+            console.log(`${logPrefix} Pushing directly to ${REMOTES.ORIGIN}/${BRANCHES.MAIN} (push-only)...`);
+            await gitWorktree.pushRefspec(REMOTES.ORIGIN, tempBranchName, BRANCHES.MAIN);
+            console.log(`${logPrefix} ✅ Pushed to ${REMOTES.ORIGIN}/${BRANCHES.MAIN}`);
+            // Fetch to update remote tracking ref (FETCH_HEAD)
+            console.log(`${logPrefix} Fetching ${REMOTES.ORIGIN}/${BRANCHES.MAIN}...`);
+            await mainGit.fetch(REMOTES.ORIGIN, BRANCHES.MAIN);
+            console.log(`${logPrefix} ✅ Fetched ${REMOTES.ORIGIN}/${BRANCHES.MAIN}`);
+            // Return FETCH_HEAD as ref for worktree creation
+            return { ...result, ref: GIT_REFS.FETCH_HEAD };
+        }
+        else {
+            // Standard path: merge to local main, then push
+            await mergeWithRetry(tempBranchName, microWorktreePath, logPrefix);
+            console.log(`${logPrefix} Pushing to ${REMOTES.ORIGIN}/${BRANCHES.MAIN}...`);
+            await mainGit.push(REMOTES.ORIGIN, BRANCHES.MAIN);
+            console.log(`${logPrefix} ✅ Pushed to ${REMOTES.ORIGIN}/${BRANCHES.MAIN}`);
+            return { ...result, ref: BRANCHES.MAIN };
+        }
+    }
+    finally {
+        // Cleanup (always runs)
+        await cleanupMicroWorktree(microWorktreePath, tempBranchName, logPrefix);
+    }
+}

package/dist/migration-deployer.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @file migration-deployer.mjs
+ * @description Migration deployment utilities for Supabase schema sync
+ * WU-1983: Sync production schema and establish migration deployment workflow
+ *
+ * Provides:
+ * - Local migration file discovery
+ * - Migration name extraction (timestamp + name)
+ * - Integration point for MCP-based deployment
+ */
+/**
+ * Default migrations directory path (relative to repo root)
+ */
+export declare const MIGRATIONS_DIR = "supabase/supabase/migrations";
+/**
+ * Extract migration info from filename
+ * @param {string} filename - Migration filename (e.g., '20251224125733_patient_documents_storage.sql')
+ * @returns {{ timestamp: string, name: string, fullName: string } | null}
+ */
+export declare function parseMigrationFilename(filename: any): {
+    timestamp: string;
+    name: string;
+    fullName: string;
+};
+/**
+ * Discover local migration files
+ * @param {string} baseDir - Base directory (repo root)
+ * @returns {{ files: Array<{ filename: string, timestamp: string, name: string, fullName: string, path: string }>, errors: string[] }}
+ */
+export declare function discoverLocalMigrations(baseDir: any): {
+    files: any[];
+    errors: any[];
+};
+/**
+ * Read migration SQL content
+ * @param {string} migrationPath - Full path to migration file
+ * @returns {string} SQL content
+ */
+export declare function readMigrationContent(migrationPath: any): string;
+/**
+ * Check if WU code_paths includes Supabase migrations
+ * @param {string[]} codePaths - Array of code paths from WU YAML
+ * @returns {boolean} True if migrations are in scope
+ */
+export declare function hasMigrationChanges(codePaths: any): boolean;
+/**
+ * Compare local migrations with production (for drift detection)
+ * @param {Array<{ fullName: string }>} localMigrations - Local migration list
+ * @param {Array<{ name: string }>} productionMigrations - Production migration list (from MCP)
+ * @returns {{ missing: string[], extra: string[], synced: boolean }}
+ */
+export declare function compareMigrations(localMigrations: any, productionMigrations: any): {
+    missing: any;
+    extra: any;
+    synced: boolean;
+};
+/**
+ * Format migration deployment report
+ * @param {{ missing: string[], extra: string[], synced: boolean }} comparison
+ * @returns {string} Formatted report
+ */
+export declare function formatMigrationReport(comparison: any): string;
+/**
+ * Build MCP migration deployment command (for documentation/agents)
+ * @param {string} migrationName - Full migration name (e.g., '20251224125733_patient_documents_storage')
+ * @param {string} sql - Migration SQL content
+ * @returns {string} MCP command description
+ */
+export declare function buildMCPDeploymentHint(migrationName: any, sql: any): string;

package/dist/migration-deployer.js

@@ -0,0 +1,151 @@
+/**
+ * @file migration-deployer.mjs
+ * @description Migration deployment utilities for Supabase schema sync
+ * WU-1983: Sync production schema and establish migration deployment workflow
+ *
+ * Provides:
+ * - Local migration file discovery
+ * - Migration name extraction (timestamp + name)
+ * - Integration point for MCP-based deployment
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Default migrations directory path (relative to repo root)
+ */
+export const MIGRATIONS_DIR = 'supabase/supabase/migrations';
+/**
+ * Migration file pattern (YYYYMMDDHHMMSS_name.sql)
+ * @type {RegExp}
+ */
+const MIGRATION_FILE_PATTERN = /^(\d{14})_(.+)\.sql$/;
+/**
+ * Extract migration info from filename
+ * @param {string} filename - Migration filename (e.g., '20251224125733_patient_documents_storage.sql')
+ * @returns {{ timestamp: string, name: string, fullName: string } | null}
+ */
+export function parseMigrationFilename(filename) {
+    const match = MIGRATION_FILE_PATTERN.exec(filename);
+    if (!match)
+        return null;
+    return {
+        timestamp: match[1],
+        name: match[2],
+        fullName: `${match[1]}_${match[2]}`,
+    };
+}
+/**
+ * Discover local migration files
+ * @param {string} baseDir - Base directory (repo root)
+ * @returns {{ files: Array<{ filename: string, timestamp: string, name: string, fullName: string, path: string }>, errors: string[] }}
+ */
+export function discoverLocalMigrations(baseDir) {
+    const migrationsPath = path.join(baseDir, MIGRATIONS_DIR);
+    const errors = [];
+    const files = [];
+    if (!existsSync(migrationsPath)) {
+        errors.push(`Migrations directory not found: ${migrationsPath}`);
+        return { files, errors };
+    }
+    try {
+        const entries = readdirSync(migrationsPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith('.sql'))
+                continue;
+            const parsed = parseMigrationFilename(entry.name);
+            if (!parsed) {
+                errors.push(`Invalid migration filename format: ${entry.name}`);
+                continue;
+            }
+            files.push({
+                filename: entry.name,
+                timestamp: parsed.timestamp,
+                name: parsed.name,
+                fullName: parsed.fullName,
+                path: path.join(migrationsPath, entry.name),
+            });
+        }
+        // Sort by timestamp (ascending)
+        files.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    }
+    catch (err) {
+        errors.push(`Error reading migrations directory: ${err.message}`);
+    }
+    return { files, errors };
+}
+/**
+ * Read migration SQL content
+ * @param {string} migrationPath - Full path to migration file
+ * @returns {string} SQL content
+ */
+export function readMigrationContent(migrationPath) {
+    return readFileSync(migrationPath, 'utf8');
+}
+/**
+ * Check if WU code_paths includes Supabase migrations
+ * @param {string[]} codePaths - Array of code paths from WU YAML
+ * @returns {boolean} True if migrations are in scope
+ */
+export function hasMigrationChanges(codePaths) {
+    if (!Array.isArray(codePaths))
+        return false;
+    const migrationPatterns = ['supabase/', 'supabase/supabase/migrations/', MIGRATIONS_DIR];
+    return codePaths.some((codePath) => migrationPatterns.some((pattern) => codePath.startsWith(pattern) || codePath === pattern.slice(0, -1)));
+}
+/**
+ * Compare local migrations with production (for drift detection)
+ * @param {Array<{ fullName: string }>} localMigrations - Local migration list
+ * @param {Array<{ name: string }>} productionMigrations - Production migration list (from MCP)
+ * @returns {{ missing: string[], extra: string[], synced: boolean }}
+ */
+export function compareMigrations(localMigrations, productionMigrations) {
+    const localNames = new Set(localMigrations.map((m) => m.fullName));
+    const prodNames = new Set(productionMigrations.map((m) => m.name));
+    // Migrations in local but not in production
+    const missing = localMigrations.filter((m) => !prodNames.has(m.fullName)).map((m) => m.fullName);
+    // Migrations in production but not in local (unusual but possible)
+    const extra = productionMigrations.filter((m) => !localNames.has(m.name)).map((m) => m.name);
+    return {
+        missing,
+        extra,
+        synced: missing.length === 0 && extra.length === 0,
+    };
+}
+/**
+ * Format migration deployment report
+ * @param {{ missing: string[], extra: string[], synced: boolean }} comparison
+ * @returns {string} Formatted report
+ */
+export function formatMigrationReport(comparison) {
+    const lines = [];
+    if (comparison.synced) {
+        lines.push('Migrations are in sync between local and production.');
+        return lines.join('\n');
+    }
+    if (comparison.missing.length > 0) {
+        lines.push('Migrations missing from production:');
+        comparison.missing.forEach((name) => lines.push(`  - ${name}`));
+        lines.push('');
+    }
+    if (comparison.extra.length > 0) {
+        lines.push('Migrations in production but not local (unexpected):');
+        comparison.extra.forEach((name) => lines.push(`  - ${name}`));
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * Build MCP migration deployment command (for documentation/agents)
+ * @param {string} migrationName - Full migration name (e.g., '20251224125733_patient_documents_storage')
+ * @param {string} sql - Migration SQL content
+ * @returns {string} MCP command description
+ */
+export function buildMCPDeploymentHint(migrationName, sql) {
+    return `To deploy ${migrationName} to production:
+
+Use mcp__supabase__apply_migration with:
+  - name: "${migrationName}"
+  - sql: <content of migration file>
+
+Or use mcp__supabase__execute_sql for individual statements.`;
+}

package/dist/orchestration-advisory-loader.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Orchestration Advisory Loader
+ *
+ * Pure JavaScript implementation of mandatory agent advisory.
+ * Uses minimatch for glob pattern matching (same as TypeScript version).
+ *
+ * @module orchestration-advisory-loader
+ * @see {@link ./orchestration-advisory.mjs} - TypeScript version for tests
+ * @see {@link ./domain/orchestration.constants.mjs} - Pattern definitions
+ */
+/**
+ * Emit mandatory agent advisory based on code paths.
+ *
+ * @param {string[]} codePaths - Array of file paths
+ * @param {string} wuId - Work Unit ID
+ */
+export declare function emitMandatoryAgentAdvisory(codePaths: any, wuId: any): void;
+/**
+ * Check mandatory agent compliance.
+ *
+ * @param {string[]} codePaths - Array of file paths
+ * @param {string} _wuId - Work Unit ID (reserved for future telemetry lookup)
+ * @returns {{compliant: boolean, missing: string[]}}
+ */
+export declare function checkMandatoryAgentsCompliance(codePaths: any, _wuId: any): {
+    compliant: boolean;
+    missing: unknown[];
+};