@lumenflow/cli 1.0.0 → 1.3.0

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

@@ -147,7 +147,7 @@ async function validateClaimMetadataBeforeGates(id, worktreePath, yamlStatus) {
         `  pnpm wu:repair-claim --id ${id}\n\n` +
         `After repair, retry:\n` +
         `  pnpm wu:done --id ${id}\n\n` +
-        `See: ai/onboarding/troubleshooting-wu-done.md for more recovery options.`);
+        `See: docs/04-operations/_frameworks/lumenflow/agent/onboarding/troubleshooting-wu-done.md for more recovery options.`);
 }
 export function printExposureWarnings(wu, options = {}) {
     // Validate exposure
@@ -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,11 +1788,13 @@ 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` +
-            `If the worktree was removed, recreate it and retry, or use --skip-gates with justification.`);
+            `If the worktree was removed, recreate it and retry, or rerun with --branch-only when the lane branch exists.\n` +
+            `Use --skip-gates only with justification.`);
     }
     // Step 0.75: Run COS governance gates (WU-614, COS v1.3 §7)
     if (!args.skipCosGates) {
@@ -1766,6 +1859,13 @@ async function executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath,
  * @param {string|null} params.derivedWorktree - Derived worktree path
  * @param {string} params.STAMPS_DIR - Stamps directory path
  */
+export function computeBranchOnlyFallback({ isBranchOnly, branchOnlyRequested, worktreeExists, derivedWorktree, }) {
+    const allowFallback = Boolean(branchOnlyRequested) && !isBranchOnly && !worktreeExists && Boolean(derivedWorktree);
+    return {
+        allowFallback,
+        effectiveBranchOnly: isBranchOnly || allowFallback,
+    };
+}
 function printStateHUD({ id, docMain, isBranchOnly, isDocsOnly, derivedWorktree, STAMPS_DIR }) {
     const stampExists = existsSync(path.join(STAMPS_DIR, `${id}.done`)) ? 'yes' : 'no';
     const yamlStatus = docMain.status || 'unknown';
@@ -1777,6 +1877,8 @@ function printStateHUD({ id, docMain, isBranchOnly, isDocsOnly, derivedWorktree,
 }
 // eslint-disable-next-line sonarjs/cognitive-complexity -- Pre-existing complexity, refactor tracked separately
 async function main() {
+    // Allow pre-push hook to recognize wu:done automation (WU-1030)
+    process.env.LUMENFLOW_WU_TOOL = 'wu-done';
     // Validate CLI arguments and WU ID format (extracted to wu-done-validators.mjs)
     const { args, id } = validateInputs(process.argv);
     // Detect workspace mode and calculate paths (WU-1215: extracted to validators module)
@@ -1784,25 +1886,39 @@ async function main() {
     const { WU_PATH, STATUS_PATH, BACKLOG_PATH, STAMPS_DIR, docMain, isBranchOnly, derivedWorktree, docForValidation: initialDocForValidation, isDocsOnly, } = pathInfo;
     // Capture main checkout path once. process.cwd() may drift later during recovery flows.
     const mainCheckoutPath = process.cwd();
+    // Resolve worktree path early so we can detect missing worktree before pre-flight checks
+    const resolvedWorktreePath = derivedWorktree && !isBranchOnly
+        ? path.isAbsolute(derivedWorktree)
+            ? derivedWorktree
+            : path.resolve(mainCheckoutPath, derivedWorktree)
+        : null;
+    const worktreeExists = resolvedWorktreePath ? existsSync(resolvedWorktreePath) : false;
+    const { allowFallback: allowBranchOnlyFallback, effectiveBranchOnly } = computeBranchOnlyFallback({
+        isBranchOnly,
+        branchOnlyRequested: args.branchOnly,
+        worktreeExists,
+        derivedWorktree,
+    });
+    if (allowBranchOnlyFallback) {
+        console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Worktree missing (${resolvedWorktreePath}). Proceeding in branch-only mode because --branch-only was provided.`);
+    }
+    const effectiveDerivedWorktree = effectiveBranchOnly ? null : derivedWorktree;
+    const effectiveWorktreePath = effectiveBranchOnly ? null : resolvedWorktreePath;
     // Pre-flight checks (WU-1215: extracted to executePreFlightChecks function)
     const preFlightResult = await executePreFlightChecks({
         id,
         args,
-        isBranchOnly,
+        isBranchOnly: effectiveBranchOnly,
         isDocsOnly,
         docMain,
         docForValidation: initialDocForValidation,
-        derivedWorktree,
+        derivedWorktree: effectiveDerivedWorktree,
     });
     const title = preFlightResult.title;
     // Note: docForValidation is returned but not used after pre-flight checks
     // The metadata transaction uses docForUpdate instead
     // Step 0: Run gates (WU-1215: extracted to executeGates function)
-    const worktreePath = derivedWorktree && !isBranchOnly
-        ? path.isAbsolute(derivedWorktree)
-            ? derivedWorktree
-            : path.resolve(mainCheckoutPath, derivedWorktree)
-        : null;
+    const worktreePath = effectiveWorktreePath;
     // WU-1943: Check if any checkpoints exist for this WU session
     // Warn (don't block) if no checkpoints - agent should have been checkpointing periodically
     try {
@@ -1816,9 +1932,16 @@ async function main() {
     catch {
         // Non-blocking: checkpoint check failure should not block wu:done
     }
-    await executeGates({ id, args, isBranchOnly, isDocsOnly, worktreePath });
+    await executeGates({ id, args, isBranchOnly: effectiveBranchOnly, isDocsOnly, worktreePath });
     // Print State HUD for visibility (WU-1215: extracted to printStateHUD function)
-    printStateHUD({ id, docMain, isBranchOnly, isDocsOnly, derivedWorktree, STAMPS_DIR });
+    printStateHUD({
+        id,
+        docMain,
+        isBranchOnly: effectiveBranchOnly,
+        isDocsOnly,
+        derivedWorktree: effectiveDerivedWorktree,
+        STAMPS_DIR,
+    });
     // Step 0.5: Pre-flight validation - run ALL pre-commit hooks BEFORE merge
     // This prevents partial completion states where merge succeeds but commit fails
     // Validates all 8 gates: secrets, file size, ESLint, Prettier, TypeScript, audit, architecture, tasks
@@ -1855,7 +1978,7 @@ async function main() {
             validateStagedFiles,
         };
         try {
-            if (isBranchOnly) {
+            if (effectiveBranchOnly) {
                 // Branch-Only mode: merge first, then update metadata on main
                 // NOTE: Branch-only still uses old rollback mechanism
                 const branchOnlyContext = {
@@ -2073,7 +2196,7 @@ async function detectChangedDocPaths(worktreePath, baseBranch) {
         // Get files changed in this branch vs base
         const diff = await git.raw(['diff', '--name-only', baseBranch]);
         const changedFiles = diff.split('\n').filter(Boolean);
-        // Filter to docs: ai/onboarding/, docs/, CLAUDE.md, README.md, *.md in root
+        // Filter to docs: docs/04-operations/_frameworks/lumenflow/agent/onboarding/, docs/, CLAUDE.md, README.md, *.md in root
         const docPatterns = [
             /^ai\/onboarding\//,
             /^docs\//,