@lumenflow/cli 1.0.0 → 1.1.0

package/dist/orchestrate-initiative.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * Orchestrate Initiative CLI
+ *
+ * Orchestrate initiative execution with parallel agent spawning.
+ * Builds execution plan based on WU dependencies and manages wave-based execution.
+ *
+ * Usage:
+ *   pnpm orchestrate:initiative --initiative INIT-001
+ *   pnpm orchestrate:initiative --initiative INIT-001 --dry-run
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { loadInitiativeWUs, loadMultipleInitiatives, buildExecutionPlan, formatExecutionPlan, calculateProgress, formatProgress, buildCheckpointWave, formatCheckpointOutput, validateCheckpointFlags, resolveCheckpointMode, LOG_PREFIX, } from '@lumenflow/initiatives';
+import { EXIT_CODES } from '@lumenflow/core/dist/wu-constants.js';
+const program = new Command()
+    .name('orchestrate-initiative')
+    .description('Orchestrate initiative execution with parallel agent spawning')
+    .option('-i, --initiative <ids...>', 'Initiative ID(s) to orchestrate')
+    .option('-d, --dry-run', 'Show execution plan without spawning agents')
+    .option('-p, --progress', 'Show current progress only')
+    .option('-c, --checkpoint-per-wave', 'Spawn next wave then exit (no polling)')
+    .option('--no-checkpoint', 'Force polling mode')
+    .action(async (options) => {
+    const { initiative: initIds, dryRun, progress: progressOnly, checkpointPerWave, checkpoint, } = options;
+    const noCheckpoint = checkpoint === false;
+    try {
+        validateCheckpointFlags({ checkpointPerWave, dryRun, noCheckpoint });
+    }
+    catch (error) {
+        console.error(chalk.red(`${LOG_PREFIX} Error: ${error.message}`));
+        process.exit(EXIT_CODES.ERROR);
+    }
+    if (!initIds || initIds.length === 0) {
+        console.error(chalk.red(`${LOG_PREFIX} Error: --initiative is required`));
+        console.error('');
+        console.error('Usage:');
+        console.error('  pnpm orchestrate:initiative --initiative INIT-001');
+        console.error('  pnpm orchestrate:initiative --initiative INIT-001 --dry-run');
+        process.exit(EXIT_CODES.ERROR);
+    }
+    try {
+        console.log(chalk.cyan(`${LOG_PREFIX} Loading initiative(s): ${initIds.join(', ')}`));
+        let wus;
+        let initiative;
+        if (initIds.length === 1) {
+            const result = loadInitiativeWUs(initIds[0]);
+            initiative = result.initiative;
+            wus = result.wus;
+        }
+        else {
+            wus = loadMultipleInitiatives(initIds);
+            initiative = { id: 'MULTI', title: `Combined: ${initIds.join(', ')}` };
+        }
+        console.log(chalk.green(`${LOG_PREFIX} Loaded ${wus.length} WU(s)`));
+        console.log('');
+        const progress = calculateProgress(wus);
+        console.log(chalk.bold('Progress:'));
+        console.log(formatProgress(progress));
+        console.log('');
+        if (progressOnly) {
+            return;
+        }
+        const checkpointDecision = resolveCheckpointMode({ checkpointPerWave, noCheckpoint, dryRun }, wus);
+        if (checkpointDecision.enabled) {
+            if (initIds.length > 1) {
+                console.error(chalk.red(`${LOG_PREFIX} Error: Checkpoint mode only supports single initiative`));
+                process.exit(EXIT_CODES.ERROR);
+            }
+            const waveData = buildCheckpointWave(initIds[0], { dryRun });
+            if (!waveData) {
+                console.log(chalk.green(`${LOG_PREFIX} All WUs are complete! Nothing to spawn.`));
+                return;
+            }
+            console.log(formatCheckpointOutput({ ...waveData, dryRun }));
+            return;
+        }
+        console.log(chalk.cyan(`${LOG_PREFIX} Building execution plan...`));
+        const plan = buildExecutionPlan(wus);
+        if (plan.waves.length === 0) {
+            console.log(chalk.green(`${LOG_PREFIX} All WUs are complete! Nothing to execute.`));
+            return;
+        }
+        console.log('');
+        console.log(chalk.bold('Execution Plan:'));
+        console.log(formatExecutionPlan(initiative, plan));
+        if (dryRun) {
+            console.log(chalk.yellow(`${LOG_PREFIX} Dry run mode - no agents spawned`));
+            console.log(chalk.cyan('To execute this plan, remove the --dry-run flag.'));
+            return;
+        }
+        console.log(chalk.green(`${LOG_PREFIX} Execution plan output complete.`));
+        console.log(chalk.cyan('Copy the spawn commands above to execute.'));
+    }
+    catch (error) {
+        console.error(chalk.red(`${LOG_PREFIX} Error: ${error.message}`));
+        process.exit(EXIT_CODES.ERROR);
+    }
+});
+program.parse();

package/dist/orchestrate-monitor.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Orchestrate Monitor CLI
+ *
+ * Monitors spawned agent progress using mem:inbox signals.
+ * Designed to prevent context exhaustion by using compact signal output.
+ *
+ * Usage:
+ *   pnpm orchestrate:monitor --since 30m
+ */
+import { Command } from 'commander';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { EXIT_CODES } from '@lumenflow/core/dist/wu-constants.js';
+import chalk from 'chalk';
+import ms from 'ms';
+const LOG_PREFIX = '[orchestrate:monitor]';
+const MEMORY_DIR = '.beacon/memory';
+function parseTimeString(timeStr) {
+    const msValue = ms(timeStr);
+    if (typeof msValue === 'number') {
+        return new Date(Date.now() - msValue);
+    }
+    const date = new Date(timeStr);
+    if (isNaN(date.getTime())) {
+        throw new Error(`Invalid time format: ${timeStr}`);
+    }
+    return date;
+}
+function loadRecentSignals(since) {
+    const signals = [];
+    if (!existsSync(MEMORY_DIR)) {
+        return signals;
+    }
+    const files = readdirSync(MEMORY_DIR).filter((f) => f.endsWith('.ndjson'));
+    for (const file of files) {
+        const filePath = join(MEMORY_DIR, file);
+        const content = readFileSync(filePath, 'utf-8');
+        const lines = content.trim().split('\n').filter(Boolean);
+        for (const line of lines) {
+            try {
+                const signal = JSON.parse(line);
+                const signalTime = new Date(signal.timestamp);
+                if (signalTime >= since) {
+                    signals.push(signal);
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+    }
+    return signals.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+}
+const program = new Command()
+    .name('orchestrate:monitor')
+    .description('Monitor spawned agent progress')
+    .option('--since <time>', 'Show signals since (e.g., 30m, 1h)', '30m')
+    .option('--wu <id>', 'Filter by WU ID')
+    .action((opts) => {
+    try {
+        const since = parseTimeString(opts.since);
+        console.log(chalk.cyan(`${LOG_PREFIX} Loading signals since ${since.toISOString()}...`));
+        const signals = loadRecentSignals(since);
+        if (signals.length === 0) {
+            console.log(chalk.yellow(`${LOG_PREFIX} No signals found.`));
+            console.log(chalk.gray('Agents may still be starting up, or memory layer not initialized.'));
+            return;
+        }
+        const filtered = opts.wu ? signals.filter((s) => s.wuId === opts.wu) : signals;
+        console.log(chalk.bold(`\nRecent Signals (${filtered.length}):\n`));
+        for (const signal of filtered) {
+            const time = new Date(signal.timestamp).toLocaleTimeString();
+            const wu = signal.wuId ? chalk.cyan(signal.wuId) : chalk.gray('system');
+            const type = signal.type === 'complete'
+                ? chalk.green(signal.type)
+                : signal.type === 'error'
+                    ? chalk.red(signal.type)
+                    : chalk.yellow(signal.type);
+            console.log(`  ${chalk.gray(time)} [${wu}] ${type}: ${signal.message || ''}`);
+        }
+        console.log('');
+        console.log(chalk.gray(`Use: pnpm mem:inbox --since ${opts.since} for more details`));
+    }
+    catch (err) {
+        console.error(chalk.red(`${LOG_PREFIX} Error: ${err.message}`));
+        process.exit(EXIT_CODES.ERROR);
+    }
+});
+program.parse();

package/dist/wu-claim.js

@@ -507,7 +507,10 @@ function validateLaneFormatWithError(lane) {
     }
 }
 /**
- * Handle lane occupancy check and enforce WIP=1 policy
+ * Handle lane occupancy check and enforce WIP limit policy
+ *
+ * WU-1016: Updated to support configurable WIP limits per lane.
+ * The WIP limit is read from .lumenflow.config.yaml and defaults to 1.
  */
 function handleLaneOccupancy(laneCheck, lane, id, force) {
     if (laneCheck.free)
@@ -517,18 +520,26 @@ function handleLaneOccupancy(laneCheck, lane, id, force) {
     }
     if (!laneCheck.occupiedBy)
         return;
+    // WU-1016: Include WIP limit info in messages
+    const wipLimit = laneCheck.wipLimit ?? 1;
+    const currentCount = laneCheck.currentCount ?? 0;
+    const inProgressList = laneCheck.inProgressWUs?.join(', ') || laneCheck.occupiedBy;
     if (force) {
-        console.warn(`${PREFIX} ⚠️  WARNING: Lane "${lane}" is occupied by ${laneCheck.occupiedBy}`);
-        console.warn(`${PREFIX} ⚠️  Forcing WIP=2 in same lane. Risk of worktree collision!`);
+        console.warn(`${PREFIX} ⚠️  WARNING: Lane "${lane}" has ${currentCount}/${wipLimit} WUs in progress`);
+        console.warn(`${PREFIX} ⚠️  In progress: ${inProgressList}`);
+        console.warn(`${PREFIX} ⚠️  Forcing WIP limit override. Risk of worktree collision!`);
         console.warn(`${PREFIX} ⚠️  Use only for P0 emergencies or manual recovery.`);
         return;
     }
-    die(`Lane "${lane}" is already occupied by ${laneCheck.occupiedBy}.\n\n` +
-        `LumenFlow enforces one-WU-per-lane to maintain focus.\n\n` +
+    die(`Lane "${lane}" is at WIP limit (${currentCount}/${wipLimit}).\n\n` +
+        `In progress: ${inProgressList}\n\n` +
+        `LumenFlow enforces WIP limits per lane to maintain focus.\n` +
+        `Current limit for "${lane}": ${wipLimit} (configure in .lumenflow.config.yaml)\n\n` +
         `Options:\n` +
-        `  1. Wait for ${laneCheck.occupiedBy} to complete or block\n` +
+        `  1. Wait for a WU to complete or block\n` +
         `  2. Choose a different lane\n` +
-        `  3. Use --force to override (P0 emergencies only)\n\n` +
+        `  3. Increase wip_limit in .lumenflow.config.yaml\n` +
+        `  4. Use --force to override (P0 emergencies only)\n\n` +
         `To check lane status: grep "${STATUS_SECTIONS.IN_PROGRESS}" docs/04-operations/tasks/status.md`);
 }
 /**

package/dist/wu-delete.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+/**
+ * WU Delete Helper
+ *
+ * Race-safe WU deletion using micro-worktree isolation.
+ *
+ * Uses micro-worktree pattern:
+ * 1) Validate inputs (WU exists, status is not in_progress)
+ * 2) Ensure main is clean and up-to-date with origin
+ * 3) Create temp branch WITHOUT switching (main checkout stays on main)
+ * 4) Create micro-worktree in /tmp pointing to temp branch
+ * 5) Delete WU file and update backlog.md in micro-worktree
+ * 6) Commit, ff-only merge, push
+ * 7) Cleanup temp branch and micro-worktree
+ *
+ * Usage:
+ *   pnpm wu:delete --id WU-123           # Single WU deletion
+ *   pnpm wu:delete --id WU-123 --dry-run # Dry run
+ *   pnpm wu:delete --batch WU-1,WU-2,WU-3 # Batch deletion
+ */
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
+import { parseYAML } from '@lumenflow/core/dist/wu-yaml.js';
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
+import { FILE_SYSTEM, EXIT_CODES, MICRO_WORKTREE_OPERATIONS, LOG_PREFIX, WU_STATUS, } from '@lumenflow/core/dist/wu-constants.js';
+import { ensureOnMain, ensureMainUpToDate, validateWUIDFormat, } from '@lumenflow/core/dist/wu-helpers.js';
+import { withMicroWorktree } from '@lumenflow/core/dist/micro-worktree.js';
+const PREFIX = LOG_PREFIX.DELETE || '[wu:delete]';
+const DELETE_OPTIONS = {
+    dryRun: {
+        name: 'dryRun',
+        flags: '--dry-run',
+        description: 'Show what would be deleted without making changes',
+    },
+    batch: {
+        name: 'batch',
+        flags: '--batch <ids>',
+        description: 'Delete multiple WUs atomically (comma-separated: WU-1,WU-2,WU-3)',
+    },
+};
+function parseArgs() {
+    return createWUParser({
+        name: 'wu-delete',
+        description: 'Safely delete WU YAML files with micro-worktree isolation',
+        options: [WU_OPTIONS.id, DELETE_OPTIONS.dryRun, DELETE_OPTIONS.batch],
+        required: [],
+        allowPositionalId: true,
+    });
+}
+function parseBatchIds(batchArg) {
+    return batchArg
+        .split(',')
+        .map((id) => id.trim().toUpperCase())
+        .filter((id) => id.length > 0);
+}
+function validateWUDeletable(id) {
+    const wuPath = WU_PATHS.WU(id);
+    if (!existsSync(wuPath)) {
+        die(`WU ${id} not found at ${wuPath}\n\nEnsure the WU exists and you're in the repo root.`);
+    }
+    const content = readFileSync(wuPath, FILE_SYSTEM.ENCODING);
+    const wu = parseYAML(content);
+    if (wu.status === WU_STATUS.IN_PROGRESS) {
+        die(`Cannot delete WU ${id}: status is '${WU_STATUS.IN_PROGRESS}'.\n\n` +
+            `WUs that are actively being worked on cannot be deleted.\n` +
+            `If the WU was abandoned, first run: pnpm wu:block --id ${id} --reason "Abandoned"\n` +
+            `Then retry the delete operation.`);
+    }
+    return { wu, wuPath };
+}
+async function ensureCleanWorkingTree() {
+    const status = await getGitForCwd().getStatus();
+    if (status.trim()) {
+        die(`Working tree is not clean. Cannot delete WU.\n\nUncommitted changes:\n${status}\n\nCommit or stash changes before deleting:\n  git add . && git commit -m "..."\n`);
+    }
+}
+function getStampPath(id) {
+    return join(WU_PATHS.STAMPS_DIR(), `${id}.done`);
+}
+function stampExists(id) {
+    return existsSync(getStampPath(id));
+}
+function removeFromBacklog(backlogPath, id) {
+    if (!existsSync(backlogPath)) {
+        return false;
+    }
+    const content = readFileSync(backlogPath, FILE_SYSTEM.ENCODING);
+    const wuLinkPattern = new RegExp(`^.*\\[${id}[^\\]]*\\].*$`, 'gmi');
+    const wuSimplePattern = new RegExp(`^.*${id}.*\\.yaml.*$`, 'gmi');
+    let updated = content.replace(wuLinkPattern, '');
+    updated = updated.replace(wuSimplePattern, '');
+    updated = updated.replace(/\n{3,}/g, '\n\n');
+    if (updated !== content) {
+        writeFileSync(backlogPath, updated, FILE_SYSTEM.ENCODING);
+        return true;
+    }
+    return false;
+}
+async function deleteSingleWU(id, dryRun) {
+    console.log(`${PREFIX} Starting WU delete for ${id}`);
+    validateWUIDFormat(id);
+    const { wu, wuPath } = validateWUDeletable(id);
+    console.log(`${PREFIX} WU details:`);
+    console.log(`${PREFIX}   Title: ${wu.title}`);
+    console.log(`${PREFIX}   Lane: ${wu.lane}`);
+    console.log(`${PREFIX}   Status: ${wu.status}`);
+    console.log(`${PREFIX}   Path: ${wuPath}`);
+    if (dryRun) {
+        console.log(`\n${PREFIX} 🔍 DRY RUN: Would delete ${id}`);
+        console.log(`${PREFIX}   - Delete file: ${wuPath}`);
+        console.log(`${PREFIX}   - Update: ${WU_PATHS.BACKLOG()}`);
+        if (stampExists(id)) {
+            console.log(`${PREFIX}   - Delete stamp: ${getStampPath(id)}`);
+        }
+        console.log(`${PREFIX} No changes made.`);
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    await ensureOnMain(getGitForCwd());
+    await ensureCleanWorkingTree();
+    await ensureMainUpToDate(getGitForCwd(), 'wu:delete');
+    console.log(`${PREFIX} Deleting via micro-worktree...`);
+    await withMicroWorktree({
+        operation: MICRO_WORKTREE_OPERATIONS.WU_DELETE,
+        id: id,
+        logPrefix: PREFIX,
+        execute: async ({ worktreePath, gitWorktree }) => {
+            const wuFilePath = join(worktreePath, wuPath);
+            const backlogFilePath = join(worktreePath, WU_PATHS.BACKLOG());
+            unlinkSync(wuFilePath);
+            console.log(`${PREFIX} ✅ Deleted ${id}.yaml`);
+            const stampPath = join(worktreePath, getStampPath(id));
+            if (existsSync(stampPath)) {
+                unlinkSync(stampPath);
+                console.log(`${PREFIX} ✅ Deleted stamp ${id}.done`);
+            }
+            const removedFromBacklog = removeFromBacklog(backlogFilePath, id);
+            if (removedFromBacklog) {
+                console.log(`${PREFIX} ✅ Removed ${id} from backlog.md`);
+            }
+            else {
+                console.log(`${PREFIX} ℹ️  ${id} was not found in backlog.md`);
+            }
+            await gitWorktree.add('.');
+            const commitMessage = `docs: delete ${id.toLowerCase()}`;
+            return {
+                commitMessage,
+                files: [],
+            };
+        },
+    });
+    console.log(`${PREFIX} ✅ Successfully deleted ${id}`);
+    console.log(`${PREFIX} Changes pushed to origin/main`);
+}
+async function deleteBatchWUs(ids, dryRun) {
+    console.log(`${PREFIX} Starting batch delete for ${ids.length} WU(s): ${ids.join(', ')}`);
+    const wusToDelete = [];
+    const stampsToDelete = [];
+    for (const id of ids) {
+        validateWUIDFormat(id);
+        const { wu, wuPath } = validateWUDeletable(id);
+        wusToDelete.push({ id, wu, wuPath });
+        if (stampExists(id)) {
+            stampsToDelete.push(id);
+        }
+    }
+    console.log(`${PREFIX} WUs to delete:`);
+    for (const { id, wu, wuPath } of wusToDelete) {
+        console.log(`${PREFIX}   ${id}: ${wu.title} (${wu.status}) - ${wuPath}`);
+    }
+    if (dryRun) {
+        console.log(`\n${PREFIX} 🔍 DRY RUN: Would delete ${ids.length} WU(s)`);
+        console.log(`${PREFIX} No changes made.`);
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    await ensureOnMain(getGitForCwd());
+    await ensureCleanWorkingTree();
+    await ensureMainUpToDate(getGitForCwd(), 'wu:delete --batch');
+    console.log(`${PREFIX} Deleting ${ids.length} WU(s) via micro-worktree...`);
+    await withMicroWorktree({
+        operation: MICRO_WORKTREE_OPERATIONS.WU_DELETE,
+        id: `batch-${ids.length}`,
+        logPrefix: PREFIX,
+        execute: async ({ worktreePath, gitWorktree }) => {
+            const backlogFilePath = join(worktreePath, WU_PATHS.BACKLOG());
+            for (const { id, wuPath } of wusToDelete) {
+                const wuFilePath = join(worktreePath, wuPath);
+                unlinkSync(wuFilePath);
+                console.log(`${PREFIX} ✅ Deleted ${id}.yaml`);
+            }
+            for (const id of stampsToDelete) {
+                const stampPath = join(worktreePath, getStampPath(id));
+                if (existsSync(stampPath)) {
+                    unlinkSync(stampPath);
+                    console.log(`${PREFIX} ✅ Deleted stamp ${id}.done`);
+                }
+            }
+            for (const { id } of wusToDelete) {
+                const removed = removeFromBacklog(backlogFilePath, id);
+                if (removed) {
+                    console.log(`${PREFIX} ✅ Removed ${id} from backlog.md`);
+                }
+            }
+            await gitWorktree.add('.');
+            const idList = ids.map((id) => id.toLowerCase()).join(', ');
+            const commitMessage = `chore(repair): delete ${ids.length} orphaned wus (${idList})`;
+            return {
+                commitMessage,
+                files: [],
+            };
+        },
+    });
+    console.log(`${PREFIX} ✅ Successfully deleted ${ids.length} WU(s)`);
+    console.log(`${PREFIX} Changes pushed to origin/main`);
+}
+async function main() {
+    const opts = parseArgs();
+    const { id, dryRun, batch } = opts;
+    if (!id && !batch) {
+        die('Must specify either --id WU-XXX or --batch WU-1,WU-2,WU-3');
+    }
+    if (id && batch) {
+        die('Cannot use both --id and --batch. Use one or the other.');
+    }
+    if (batch) {
+        const ids = parseBatchIds(batch);
+        if (ids.length === 0) {
+            die('--batch requires at least one WU ID');
+        }
+        await deleteBatchWUs(ids, dryRun);
+    }
+    else {
+        await deleteSingleWU(id, dryRun);
+    }
+}
+main().catch((err) => {
+    console.error(`${PREFIX} ❌ ${err.message}`);
+    process.exit(EXIT_CODES.ERROR);
+});

package/dist/wu-done.js

@@ -174,6 +174,77 @@ export function validateAccessibilityOrDie(wu, options = {}) {
             `This gate prevents "orphaned code" - features that exist but users cannot access.`);
     }
 }
+export function validateDocsOnlyFlag(wu, args) {
+    // If --docs-only flag is not used, no validation needed
+    if (!args.docsOnly) {
+        return { valid: true, errors: [] };
+    }
+    const wuId = wu.id || 'unknown';
+    const exposure = wu.exposure;
+    const type = wu.type;
+    const codePaths = wu.code_paths;
+    // Check 1: exposure is 'documentation'
+    if (exposure === 'documentation') {
+        return { valid: true, errors: [] };
+    }
+    // Check 2: type is 'documentation'
+    if (type === 'documentation') {
+        return { valid: true, errors: [] };
+    }
+    // Check 3: all code_paths are documentation paths
+    const DOCS_ONLY_PREFIXES = ['docs/', 'ai/', '.claude/', 'memory-bank/'];
+    const DOCS_ONLY_ROOT_FILES = ['readme', 'claude'];
+    const isDocsPath = (p) => {
+        const path = p.trim().toLowerCase();
+        // Check docs prefixes
+        for (const prefix of DOCS_ONLY_PREFIXES) {
+            if (path.startsWith(prefix))
+                return true;
+        }
+        // Check markdown files
+        if (path.endsWith('.md'))
+            return true;
+        // Check root file patterns
+        for (const pattern of DOCS_ONLY_ROOT_FILES) {
+            if (path.startsWith(pattern))
+                return true;
+        }
+        return false;
+    };
+    if (codePaths && Array.isArray(codePaths) && codePaths.length > 0) {
+        const allDocsOnly = codePaths.every((p) => typeof p === 'string' && isDocsPath(p));
+        if (allDocsOnly) {
+            return { valid: true, errors: [] };
+        }
+    }
+    // Validation failed - provide clear error message
+    const currentExposure = exposure || 'not set';
+    const currentType = type || 'not set';
+    return {
+        valid: false,
+        errors: [
+            `--docs-only flag used on ${wuId} but WU is not documentation-focused.\n\n` +
+                `Current exposure: ${currentExposure}\n` +
+                `Current type: ${currentType}\n\n` +
+                `--docs-only requires one of:\n` +
+                `  1. exposure: documentation\n` +
+                `  2. type: documentation\n` +
+                `  3. All code_paths under docs/, ai/, .claude/, or *.md files\n\n` +
+                `To fix, either:\n` +
+                `  - Remove --docs-only flag and run full gates\n` +
+                `  - Change WU exposure to 'documentation' if this is truly a docs-only change`,
+        ],
+    };
+}
+export function buildGatesCommand(options) {
+    const { docsOnly = false, isDocsOnly = false } = options;
+    // Use docs-only gates if either explicit flag or auto-detected
+    const shouldUseDocsOnly = docsOnly || isDocsOnly;
+    if (shouldUseDocsOnly) {
+        return `${PKG_MANAGER} ${SCRIPTS.GATES} -- ${CLI_FLAGS.DOCS_ONLY}`;
+    }
+    return `${PKG_MANAGER} ${SCRIPTS.GATES}`;
+}
 async function assertWorktreeWUInProgressInStateStore(id, worktreePath) {
     const resolvedWorktreePath = path.resolve(worktreePath);
     const stateDir = path.join(resolvedWorktreePath, '.beacon', 'state');
@@ -810,15 +881,27 @@ function checkNodeModulesStaleness(worktreePath) {
         console.warn(`${LOG_PREFIX.DONE} Could not check node_modules staleness: ${e.message}`);
     }
 }
-function runGatesInWorktree(worktreePath, id, isDocsOnly = false) {
+/**
+ * Run gates in worktree
+ * @param {string} worktreePath - Path to worktree
+ * @param {string} id - WU ID
+ * @param {object} options - Gates options
+ * @param {boolean} options.isDocsOnly - Auto-detected docs-only from code_paths
+ * @param {boolean} options.docsOnly - Explicit --docs-only flag from CLI
+ */
+function runGatesInWorktree(worktreePath, id, options = {}) {
+    const { isDocsOnly = false, docsOnly = false } = options;
     console.log(`\n${LOG_PREFIX.DONE} Running gates in worktree: ${worktreePath}`);
     // Check for stale node_modules before running gates (prevents confusing failures)
     checkNodeModulesStaleness(worktreePath);
-    const gatesCmd = isDocsOnly
-        ? `${PKG_MANAGER} ${SCRIPTS.GATES} -- ${CLI_FLAGS.DOCS_ONLY}`
-        : `${PKG_MANAGER} ${SCRIPTS.GATES}`;
-    if (isDocsOnly) {
+    // WU-1012: Use docs-only gates if explicit --docs-only flag OR auto-detected
+    const useDocsOnlyGates = docsOnly || isDocsOnly;
+    const gatesCmd = buildGatesCommand({ docsOnly, isDocsOnly });
+    if (useDocsOnlyGates) {
         console.log(`${LOG_PREFIX.DONE} Using docs-only gates (skipping lint/typecheck/tests)`);
+        if (docsOnly) {
+            console.log(`${LOG_PREFIX.DONE} (explicit --docs-only flag)`);
+        }
     }
     const startTime = Date.now();
     try {
@@ -1544,6 +1627,11 @@ async function executePreFlightChecks({ id, args, isBranchOnly, isDocsOnly, docM
         console.warn(`\nThis is a NON-BLOCKING warning.`);
         console.warn(`Use --require-agents to make this a blocking error.\n`);
     }
+    // WU-1012: Validate --docs-only flag usage (BLOCKING)
+    const docsOnlyValidation = validateDocsOnlyFlag(docForValidation, { docsOnly: args.docsOnly });
+    if (!docsOnlyValidation.valid) {
+        die(docsOnlyValidation.errors[0]);
+    }
     // WU-1999: Exposure validation (NON-BLOCKING warning)
     printExposureWarnings(docForValidation, { skipExposureCheck: args.skipExposureCheck });
     // WU-2022: Feature accessibility validation (BLOCKING)
@@ -1656,11 +1744,14 @@ async function executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath,
     else if (isBranchOnly) {
         // Branch-Only mode: run gates in-place (current directory on lane branch)
         console.log(`\n${LOG_PREFIX.DONE} Running gates in Branch-Only mode (in-place on lane branch)`);
-        const gatesCmd = isDocsOnly
-            ? `${PKG_MANAGER} ${SCRIPTS.GATES} -- ${CLI_FLAGS.DOCS_ONLY}`
-            : `${PKG_MANAGER} ${SCRIPTS.GATES}`;
-        if (isDocsOnly) {
+        // WU-1012: Use docs-only gates if explicit --docs-only flag OR auto-detected
+        const useDocsOnlyGates = args.docsOnly || isDocsOnly;
+        const gatesCmd = buildGatesCommand({ docsOnly: Boolean(args.docsOnly), isDocsOnly });
+        if (useDocsOnlyGates) {
             console.log(`${LOG_PREFIX.DONE} Using docs-only gates (skipping lint/typecheck/tests)`);
+            if (args.docsOnly) {
+                console.log(`${LOG_PREFIX.DONE} (explicit --docs-only flag)`);
+            }
         }
         const startTime = Date.now();
         try {
@@ -1697,7 +1788,8 @@ async function executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath,
     }
     else if (worktreePath && existsSync(worktreePath)) {
         // Worktree mode: run gates in the dedicated worktree
-        runGatesInWorktree(worktreePath, id, isDocsOnly);
+        // WU-1012: Pass both auto-detected and explicit docs-only flags
+        runGatesInWorktree(worktreePath, id, { isDocsOnly, docsOnly: Boolean(args.docsOnly) });
     }
     else {
         die(`Worktree not found (${worktreePath || 'unknown'}). Gates must run in the lane worktree.\n` +